Skip to main content
bidiDocs Dashboard

API reference

Contacts

The people the workspace knows: their details, attributes and whether your site verified them.

All endpoint groups

GET /contacts

List contacts

The workspace's contacts, most recently seen first: who they are, how to reach them, their attributes and whether a host site verified them. Filter by email, phone or external_id to look one person up. A key limited to some agents lists the contacts of those agents.

Scope: contacts: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.

  • email optional in the query · string

    Only the contact with this email (any casing).

  • phone optional in the query · string

    Only the contact with this phone number, however it is written.

  • external_id optional in the query · string

    Only the contact with this external_id.

  • verified optional in the query · boolean

    Only verified (true) or unverified (false) contacts.

Returns Contact

  • id required string

    Id

  • external_id optional string

    Your own id for this person; null when none was given.

  • name required string

    Name

  • email required string

    Email

  • phone required string

    Phone

  • attributes required object

    A flat object of text, numbers and booleans.

  • verified required boolean

    True when a host site proved this person's identity with an agent's identity secret.

  • source required string

    How the contact first arrived: manual, import, identify, lead or api.

  • first_seen_at optional string

    First Seen At

  • last_seen_at optional string

    Last Seen At

  • created_at optional string

    Created At

  • updated_at optional string

    Updated At

  • consent_marketing optional boolean

    The person explicitly agreed to campaign emails.

  • consent_marketing_at optional string

    Consent Marketing At

  • locale optional string

    The language campaign emails reach them in: en, ar, or empty.

  • marketing_status optional string

    subscribed, not_subscribed, unsubscribed, bounced or complained.

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
curl https://www.bidii.ai/api/v2/contacts \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

POST /contacts

Create or update a contact

Add a person, or complete the contact they already are: matched by external_id, then by email, then by phone. Send at least one of the three. A new contact answers 201 with a Location; an existing one answers 200 with the values you sent written over it (an empty value leaves what is there) and attributes merged by key. An email or phone that already belongs to another contact is kept for reading and does not become a second key for the same number. New contacts emit contact.created. Needs a key that reaches every agent.

Scope: contacts:write

Request body

  • external_id optional string

    Your own id for this person. Unique in the workspace.

  • name optional string

    Name

  • email optional string

    Email

  • phone optional string

    Phone

  • attributes optional object

    A flat object: up to 20 keys (lower-case names), values of text (200 characters), numbers or booleans.

  • consent_marketing optional boolean

    True only when the person explicitly agreed to campaign emails from you; false withdraws it. A person who unsubscribed, bounced or complained is not given consent again; the rest of the contact is still saved.

  • locale optional string

    The language campaign emails reach them in: en or ar (an empty string clears it).

Returns Contact

  • id required string

    Id

  • external_id optional string

    Your own id for this person; null when none was given.

  • name required string

    Name

  • email required string

    Email

  • phone required string

    Phone

  • attributes required object

    A flat object of text, numbers and booleans.

  • verified required boolean

    True when a host site proved this person's identity with an agent's identity secret.

  • source required string

    How the contact first arrived: manual, import, identify, lead or api.

  • first_seen_at optional string

    First Seen At

  • last_seen_at optional string

    Last Seen At

  • created_at optional string

    Created At

  • updated_at optional string

    Updated At

  • consent_marketing optional boolean

    The person explicitly agreed to campaign emails.

  • consent_marketing_at optional string

    Consent Marketing At

  • locale optional string

    The language campaign emails reach them in: en, ar, or empty.

  • marketing_status optional string

    subscribed, not_subscribed, unsubscribed, bounced or complained.

Responses

  • 201 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.
  • 200 The person was already a contact and was completed.
curl
curl -X POST https://www.bidii.ai/api/v2/contacts \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "u_42", "name": "Sara", "email": "sara@example.ae", "attributes": {"plan": "Gold"}}'

GET /contacts/{contact_id}

Get a contact

One contact by id.

Scope: contacts:read

Parameters

  • contact_id required in the path · string

Returns Contact

  • id required string

    Id

  • external_id optional string

    Your own id for this person; null when none was given.

  • name required string

    Name

  • email required string

    Email

  • phone required string

    Phone

  • attributes required object

    A flat object of text, numbers and booleans.

  • verified required boolean

    True when a host site proved this person's identity with an agent's identity secret.

  • source required string

    How the contact first arrived: manual, import, identify, lead or api.

  • first_seen_at optional string

    First Seen At

  • last_seen_at optional string

    Last Seen At

  • created_at optional string

    Created At

  • updated_at optional string

    Updated At

  • consent_marketing optional boolean

    The person explicitly agreed to campaign emails.

  • consent_marketing_at optional string

    Consent Marketing At

  • locale optional string

    The language campaign emails reach them in: en, ar, or empty.

  • marketing_status optional string

    subscribed, not_subscribed, unsubscribed, bounced or complained.

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
curl https://www.bidii.ai/api/v2/contacts/CONTACT_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

PATCH /contacts/{contact_id}

Update a contact

Change any of name, email, phone and attributes. Only what you send changes. An email or phone that already belongs to another contact answers 409.

Scope: contacts:write

Parameters

  • contact_id required in the path · string

Request body

  • name optional string

    Name

  • email optional string

    An empty string clears it.

  • phone optional string

    An empty string clears it.

  • attributes optional object

    Merged by key; a null value removes its key.

  • consent_marketing optional boolean

    True only when the person explicitly agreed to campaign emails from you; false withdraws it. A person who unsubscribed, bounced or complained cannot be given consent again (409 conflict, marketing_suppressed).

  • locale optional string

    The language campaign emails reach them in: en or ar (an empty string clears it).

Returns Contact

  • id required string

    Id

  • external_id optional string

    Your own id for this person; null when none was given.

  • name required string

    Name

  • email required string

    Email

  • phone required string

    Phone

  • attributes required object

    A flat object of text, numbers and booleans.

  • verified required boolean

    True when a host site proved this person's identity with an agent's identity secret.

  • source required string

    How the contact first arrived: manual, import, identify, lead or api.

  • first_seen_at optional string

    First Seen At

  • last_seen_at optional string

    Last Seen At

  • created_at optional string

    Created At

  • updated_at optional string

    Updated At

  • consent_marketing optional boolean

    The person explicitly agreed to campaign emails.

  • consent_marketing_at optional string

    Consent Marketing At

  • locale optional string

    The language campaign emails reach them in: en, ar, or empty.

  • marketing_status optional string

    subscribed, not_subscribed, unsubscribed, bounced or complained.

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.
  • 409 conflict: details says why: contact_exists, the email or phone belongs to another contact; marketing_suppressed, the person unsubscribed, so consent cannot be given for them.
curl
curl -X PATCH https://www.bidii.ai/api/v2/contacts/CONTACT_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"attributes": {"plan": "Platinum"}}'

DELETE /contacts/{contact_id}

Delete a contact

Delete the contact, everything an agent remembers of them and their leads. Their conversations stay, no longer linked to a contact. Needs a key that reaches every agent; a contact with leads needs leads:write as well (403 insufficient_scope otherwise, and nothing is deleted).

Scope: contacts:write

Parameters

  • contact_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
curl -X DELETE https://www.bidii.ai/api/v2/contacts/CONTACT_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"