Skip to content
Contacts

Fetch a contact by id

GET
/{phone_number_id}/contacts/{id}
const url = 'https://api.kirimdev.com/v1/106540352242922/contacts/ctc_01HXYZABCDEFGHJKMNPQRSTVWX';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}

Fetch one contact belonging to this WhatsApp account. Phone number, BSUID, and username fields may be null depending on which identity Meta has shared.

phone_number_id
required

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

string
/^\d{6,20}$/
Example
106540352242922

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

id
required

Public Kirimdev contact ID.

string
/^ctc_[0-9A-HJKMNP-TV-Z]{26}$/
Example
ctc_01HXYZABCDEFGHJKMNPQRSTVWX

Public Kirimdev contact ID.

Contact resource

Media type application/json
object
data
required
object
id
required
string
object
required
string
Allowed values: contact
phone_number
required

Phone number in E.164. NULL when the contact was created via BSUID (username-adopted user with no shared phone number). See docs/meta-docs/bsuid.md.

string | null
bsuid
required

Business-Scoped User ID. Populated by inbound webhooks or when the contact was created via BSUID. Format: {ISO alpha-2 country}.{alphanumeric ≤128}.

string | null
parent_bsuid
required

Parent BSUID (managed businesses only). Format: {ISO alpha-2 country}.ENT.{alphanumeric ≤128}.

string | null
username
required

WhatsApp username of the contact, if the user has adopted the username feature. Case-insensitive when comparing per Meta rules; . and _ are significant.

string | null
name
required
string | null
email
required
string | null
metadata
required
object | null
labels
required

Labels currently attached to this contact.

Array<object>
object
id
required
string
name
required
string
color
required
string
Allowed values: gray red orange amber yellow lime green emerald teal sky blue violet pink
whatsapp_account
required
object
phone_number
required
string | null
phone_number_id
required

Meta business_phone_number_id — use as the {phone_number_id} path segment in /v1/{phone_number_id}/... endpoints.

string | null
customer
required

End-customer (multi-tenant platform mode) that owns this account. NULL for direct-org accounts.

object
id
required
string
name
required
string
created_at
required
string format: date-time
updated_at
required
string format: date-time
request_id
required

Unique request identifier to include when contacting support.

string
Example
{
"data": {
"id": "ctc_01HXYZABCDEFGHJKMNPQRSTVWX",
"object": "contact",
"phone_number": "+628123456789",
"bsuid": "US.13491208655302741918",
"parent_bsuid": "US.ENT.11815799212886844830",
"username": "pablomorales",
"labels": [
{
"id": "lbl_01HXYZABCDEFGHJKMNPQRSTVWX",
"name": "VIP",
"color": "gray"
}
],
"whatsapp_account": {
"phone_number_id": "106540352242922",
"customer": {
"id": "cus_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}
},
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}

Validation failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

A field value is invalid.

{
"error": {
"type": "invalid_request_error",
"code": "invalid_field_value",
"message": "A field value is invalid.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Authentication failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The provided API key is invalid.

{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Resource not found

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Resource not found.

{
"error": {
"type": "not_found",
"code": "resource_not_found",
"message": "Resource not found.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The WhatsApp number is not connected. Check its status in the Kirimdev dashboard and reconnect it if needed.

{
"error": {
"type": "invalid_request_error",
"code": "whatsapp_number_not_verified",
"message": "The WhatsApp number is not connected. Check its status in the Kirimdev dashboard and reconnect it if needed.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Rate limit exceeded

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Rate limit exceeded.

{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Internal server error

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

An unexpected error occurred.

{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "An unexpected error occurred.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}