Public API Lead Endpoint

This endpoint lets an external system submit a lead to a specific brayv.ai account. A successful request creates or updates a contact immediately, records submission history, and queues background lead processing such as journey routing, opportunity creation, assignment, and notifications.

Endpoint

POST https://api.brayv.ai/v1/accounts/{account_id}/leads
Authorization: Bearer {api_key}
Content-Type: application/json

Replace {account_id} with the brayv.ai account ID receiving the lead.

Authentication

Send the API key in the Authorization header:

Authorization: Bearer brayv_live_...

Each API key is scoped to either one account or an organization that has access to the target account. The same key also authorizes the related endpoints below.

Related Endpoints

Response

Successful submissions return immediately after the contact is created or updated and the background processing job is queued.

{
  "status": "success",
  "submission_id": "e7ac371f-478e-4290-b147-524a0f491ab2",
  "contact_id": "34726940-88ec-49e3-9529-6e0845703eda",
  "idempotent_replay": false,
  "ignored_fields": [],
  "account_status": "active",
  "notice": null
}

Account Paused for a Payment Issue

If the target account's payment method has failed or its wallet is empty, brayv.ai pauses outbound activity for that account until billing is fixed. Submissions still succeed: the contact is created and the lead is routed into its journey, but no texts, calls, or AI outreach go out until the account admin resolves the payment issue. Journey steps that come due while the account is paused are held, and are re-scheduled at their normal interval once billing recovers.

{
  "status": "success",
  "submission_id": "e7ac371f-478e-4290-b147-524a0f491ab2",
  "contact_id": "34726940-88ec-49e3-9529-6e0845703eda",
  "idempotent_replay": false,
  "ignored_fields": [],
  "account_status": "frozen",
  "notice": "Account is paused for a payment issue. The contact was created, but no outbound outreach will occur until the payment issue is resolved."
}

Account Inactive

If the target account's brayv.ai subscription has been cancelled, the request returns 403 Forbidden. The contact is still created so the data is there when the account reactivates, but nothing else happens: no opportunity, no journey, no outreach. Have an account admin reactivate the subscription, then resubmit. Do not treat this as a transient error; retrying without reactivating will keep returning 403.

{
  "detail": {
    "code": "account_inactive",
    "message": "Account is inactive. Please have an account admin reactivate the Brayv subscription.",
    "contact_id": "34726940-88ec-49e3-9529-6e0845703eda",
    "submission_id": "e7ac371f-478e-4290-b147-524a0f491ab2"
  }
}

Required Fields

Recommended Fields

These fields are not required, but they are strongly recommended because they are commonly used in scripted engagement messages and AI agent instructions.

Consent Behavior

Opt-out fields do not block contact creation or opportunity creation. They control outreach eligibility.

The Two Voice AI Fields

A contact carries two separate voice AI settings, and they answer different questions:

Both default to true, so voice AI is available unless you say otherwise. Send has_voice_ai: false for a contact who should only ever deal with a human, and use voice_ai_opt_in: false for contacts where you did not explictly gather consent to call them using AI.

has_voice_ai: false implies no AI dialing regardless of voice_ai_opt_in, since it turns voice AI off in both directions. The two fields are stored independently, so you can still send voice_ai_opt_in: true alongside it, and the outbound flag will read true while has_voice_ai keeps the AI away from the contact.

Both fields are enforced. An AI voice agent asked to dial a contact whose has_voice_ai or has_voice_ai_outbound is false does not place the call, and the reason is recorded on the contact's activity history. A contact whose has_voice_ai is false who calls one of the account's Voice AI numbers is forwarded to a person instead of reaching an agent.

dnd_calls remains the broadest setting and covers the whole team, not just the AI: it also blocks calls placed by hand from the in-app dialer. call_opt_in: false sets it, and it is what to rely on for a contact who asked not to be called by anyone.

Required Formats

Phone

Only these formats are accepted:

Formatted numbers such as (555) 123-4567, 555-123-4567, or numbers with spaces are rejected. Rejected submissions are still logged, but no contact is created.

Email

email is optional. If provided, it must match a basic email pattern:

[email protected]

If the email does not match, the submission can still succeed, but the email is ignored and not saved to the contact.

Dates

birthday and date custom fields should be parseable date strings. ISO format is recommended:

YYYY-MM-DD

Invalid optional dates are ignored and logged.

Optional Standard Contact Fields

Unknown fields are ignored and logged. These standard contact fields are accepted:

Forwarding Facebook Instant-Form Leads

If your team collects Facebook instant-form leads in its own system first (your CRM, Zapier, or an agency's tool) and forwards them here, include Meta's IDs with each lead. brayv.ai then treats the lead exactly like one it received from Facebook directly:

Send both facebook_lead_id and campaign_id. Neither works on its own:

• With only facebook_lead_id, the lead counts as a Facebook ad lead but isn't credited to any campaign, so it's missing from that campaign's results.
• With only campaign_id, the lead isn't recognized as coming from a Facebook ad at all.

Without facebook_ad_id, the lead still counts toward its campaign but shows as unmatched in By set of ads. Send Meta's numeric IDs exactly as Facebook provides them, not campaign or ad names.

Send these with the lead itself. Ad credit is decided when the lead is submitted, so adding them later through the Contact Update API doesn't change it.

Don't also connect the form in brayv.ai. brayv.ai only imports a Facebook form's leads directly once that form is mapped under Settings > Lead Sources; until then it skips them on purpose, so teams that forward leads themselves aren't double-counted. If you forward a form's leads through this API, leave that form unmapped in brayv.ai, or every lead will arrive twice. See Facebook Lead Forms.

The journey, assignment, and notifications come from the API lead source the request is sent to, like any other API lead.

Accepted timezone Values

US/Eastern
US/Central
US/Mountain
US/Pacific
US/Alaska
US/Hawaii
America/New_York
America/Detroit
America/Toronto
America/Montreal
America/Chicago
America/Winnipeg
America/Denver
America/Edmonton
America/Phoenix
America/Los_Angeles
America/Vancouver
America/Anchorage
Pacific/Honolulu
America/Halifax
America/St_Johns

If timezone is provided and is not one of these values, it is ignored and logged.

Custom Fields

Custom fields should be sent inside the custom_fields object.

{
  "custom_fields": {
    "service_type": "HVAC",
    "lead_priority": "High"
  }
}

The key must match the custom field ID configured in brayv.ai. Use the Custom Fields API to list an account's field IDs, types, and options.

Custom field validation:

Invalid optional custom field values do not fail the submission. They are ignored and logged in submission history.

Note

note is optional and attaches a single note to the contact. It is not a contact field; it creates a note on the contact's Notes panel in brayv.ai.

{
  "note": {
    "content": "Homeowner says the upstairs unit is the problem, downstairs is fine.",
    "surface_to_agents": true
  }
}

Tip: if surfacing to agents, and the note is derived from something like an open ended 'comments' section on a lead form, it's good practice to pass in that context, i.e.:

{
  "note": {
    "content": "Comment submitted on quote request form: the upstairs unit is the problem, downstairs is fine.",
    "surface_to_agents": true
  }
}

A plain string is also accepted as shorthand, and leaves surface_to_agents at its default of false:

{
  "note": "Homeowner says the upstairs unit is the problem."
}

Note Visibility

surface_to_agents controls who can read the note:

Send surface_to_agents: true only for context an AI agent should know, and keep it false for internal commentary you do not want repeated to the contact. An agent reads at most the 3 most recently edited surfaced notes on a contact, so a surfaced note can push an older one out of view.

Note Behavior

Notes created this way are labelled Integration in brayv.ai and show no author, since they did not come from a team member.

Idempotency

idempotency_key is optional.

When provided, repeated requests with the same API key, target account, and idempotency key within about 5 minutes return the same result instead of creating a second submission.

{
  "idempotency_key": "external-lead-123"
}

Use a unique idempotency key per lead from your system.

Full Example Payload

{
  "phone": "5551234567",
  "full_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "source": "angi",
  "text_opt_in": true,
  "call_opt_in": true,
  "voice_ai_opt_in": false,
  "has_voice_ai": true,
  "idempotency_key": "angi-lead-12345",
  "email": "[email protected]",
  "business_name": "Doe Family Home",
  "website": "https://example.com",
  "timezone": "US/Eastern",
  "additional_phones": ["+15557654321"],
  "additional_emails": ["[email protected]"],
  "street_address": "123 Main St",
  "city": "Charlotte",
  "state": "NC",
  "zip_code": "28202",
  "country": "US",
  "tags": ["angi", "priority-lead"],
  "friendly_source": "Angi",
  "hook": "HVAC repair",
  "service_description": "Customer says the AC is not cooling and wants service this week.",
  "utm_source": "angi",
  "utm_medium": "lead_partner",
  "utm_campaign": "summer_hvac",
  "utm_content": "ac_repair",
  "utm_keyword": "emergency ac repair",
  "referrer": "https://www.angi.com/",
  "landing_page_url": "https://example.com/hvac",
  "facebook_click_id": "fbclid-example",
  "google_click_id": "gclid-example",
  "google_wbraid": "wbraid-example",
  "google_gbraid": "gbraid-example",
  "facebook_lead_id": "1234567890123456",
  "campaign_id": "120210000000000000",
  "facebook_ad_id": "120210000000000123",
  "custom_fields": {
    "service_type": "HVAC",
    "lead_priority": "High",
    "preferred_service_date": "2026-06-15"
  },
  "note": {
    "content": "Customer says the AC is not cooling upstairs only, and asked us to call before 5pm.",
    "surface_to_agents": true
  }
}

Example cURL

curl -X POST "https://api.brayv.ai/v1/accounts/ACCOUNT_ID/leads" \
  -H "Authorization: Bearer brayv_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5551234567",
    "full_name": "Jane Doe",
    "source": "angi",
    "text_opt_in": true,
    "call_opt_in": true,
    "voice_ai_opt_in": false,
    "idempotency_key": "angi-lead-12345",
    "friendly_source": "Angi",
    "hook": "HVAC repair",
    "custom_fields": {
      "service_type": "HVAC",
      "lead_priority": "High"
    }
  }'

Error Example

Invalid required fields return a validation error. The rejected submission is still recorded in submission history.

{
  "detail": {
    "message": "Invalid lead submission",
    "submission_id": "e7ac371f-478e-4290-b147-524a0f491ab2",
    "validation_errors": [
      {
        "field": "phone",
        "reason": "Phone must be one of: +1XXXXXXXXXX, 1XXXXXXXXXX, or XXXXXXXXXX where the leading digit is not 1"
      }
    ]
  }
}