Leads

GET /leads

List leads

Leads across the workspace's agents, newest first: name, how to reach them, what they asked about, the agent's own fields in data, the team's notes, and the conversation they came from.

Scope: leads:read

Parameters

• limit optional in the query · integer

  Rows per page, 1 to 100.

• cursor optional in the query · string

  The next_cursor of the previous page.

• agent_id optional in the query · string

  Only leads captured by this agent.

• status optional in the query · "new" | "qualified" | "closed"

  Only leads in this status.

Returns Lead

• id required string

  Id

• agent_id optional string

  Agent Id

• name optional string

  Name

• contact optional string

  Contact

• interest optional string

  Interest

• channel optional string

  Channel

• status required string

  new, qualified or closed.

• data optional object

  The agent's lead fields and job details, by key.

• notes optional string

  The team's own notes on the lead.

• conversation_id optional string

  Conversation Id

• created_at required string

  Created At

• updated_at optional string

  When the lead was last edited; null until it is.

• utm optional object

  The campaign that brought the visitor: any of utm_source, utm_medium, utm_campaign, utm_term and utm_content, as the first page of the visit carried them. Empty when there was none. Read from the lead's conversation.

• referrer optional string

  The site that sent the visitor (scheme, host and path, never the query string). Empty when there was none. Read from the lead's conversation.

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/leads \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

GET /leads/{lead_id}

Get a lead

One lead by id.

Scope: leads:read

Parameters

• lead_id required in the path · string

Returns Lead

• id required string

  Id

• agent_id optional string

  Agent Id

• name optional string

  Name

• contact optional string

  Contact

• interest optional string

  Interest

• channel optional string

  Channel

• status required string

  new, qualified or closed.

• data optional object

  The agent's lead fields and job details, by key.

• notes optional string

  The team's own notes on the lead.

• conversation_id optional string

  Conversation Id

• created_at required string

  Created At

• updated_at optional string

  When the lead was last edited; null until it is.

• utm optional object

  The campaign that brought the visitor: any of utm_source, utm_medium, utm_campaign, utm_term and utm_content, as the first page of the visit carried them. Empty when there was none. Read from the lead's conversation.

• referrer optional string

  The site that sent the visitor (scheme, host and path, never the query string). Empty when there was none. Read from the lead's conversation.

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/leads/LEAD_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

PATCH /leads/{lead_id}

Update a lead

Change any of: status (new, qualified, closed), name, contact, interest, notes, and data (merged into the lead's fields by key; a null removes a key; a select field takes only one of its options). Send at least one. A status change emits lead.status_changed; every change emits lead.updated.

Scope: leads:write

Parameters

• lead_id required in the path · string

Request body

• status optional "new" | "qualified" | "closed"

  Status

• name optional string

  Name

• contact optional string

  Contact

• interest optional string

  Interest

• notes optional string

  Notes

• data optional object

  Data

Returns Lead

• id required string

  Id

• agent_id optional string

  Agent Id

• name optional string

  Name

• contact optional string

  Contact

• interest optional string

  Interest

• channel optional string

  Channel

• status required string

  new, qualified or closed.

• data optional object

  The agent's lead fields and job details, by key.

• notes optional string

  The team's own notes on the lead.

• conversation_id optional string

  Conversation Id

• created_at required string

  Created At

• updated_at optional string

  When the lead was last edited; null until it is.

• utm optional object

  The campaign that brought the visitor: any of utm_source, utm_medium, utm_campaign, utm_term and utm_content, as the first page of the visit carried them. Empty when there was none. Read from the lead's conversation.

• referrer optional string

  The site that sent the visitor (scheme, host and path, never the query string). Empty when there was none. Read from the lead's conversation.

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl -X PATCH https://www.bidii.ai/api/v2/leads/LEAD_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "qualified"}'

DELETE /leads/{lead_id}

Delete a lead

Delete the lead for good. The conversation it came from and any booking made for it stay, no longer linked to it. The workspace's audit log records that a lead was deleted, and by which key.

Scope: leads:write

Parameters

• lead_id required in the path · string

Responses

• 204 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl -X DELETE https://www.bidii.ai/api/v2/leads/LEAD_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

GET /agents/{agent_id}/lead-fields

List an agent's lead fields

The extra details this agent collects with a lead, in the order the owner arranged them: the key each value is stored under in a lead's data, its English and Arabic labels, its kind and, for a select, its options.

Scope: leads:read

Parameters

• agent_id required in the path · string

Returns LeadField

• id required string

  Id

• agent_id required string

  Agent Id

• key required string

  The name the value is stored under in a lead's data.

• label_en required string

  Label En

• label_ar required string

  The Arabic label; empty when the owner gave none.

• kind required string

  text, email, phone, number, date or select.

• options required string[]

  The choices of a select field.

• required required boolean

  Required

• ask_when required string

  always or if_missing.

• position required integer

  Position

• created_at optional string

  Created At

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/agents/AGENT_ID/lead-fields \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"