Chatofy API

/

Getting Started

API Resources

API v1.0 Live

Developer APIContactsList Contacts

List Contacts

Retrieves a paginated list of contacts. Supports filtering by phone, UUID, owner, and lifecycle.

GET/api/v1/contacts

Note

Each contact record includes BSUID fields (user_id, username, parent_user_id, last_bsuid_sync) for Business-Scoped User ID compatibility.

Query Parameters

6 parameters

limitnumberrequired

Max results per page (default: 100, max: 100).

offsetnumberrequired

Number of records to skip (default: 0).

phonestringrequired

Filter by phone number (e.g. +919000000000).

iduuidrequired

Filter by contact UUID.

owner_iduuid|stringrequired

Filter by owner UUID, or "unassigned".

lifecyclestringrequired

Filter by lifecycle: lead, customer, at_risk, churned.

Response Payload

200 OKapplication/json

successbooleanrequired

Whether request succeeded

messagestringrequired

Human-readable result

data[]array<object>required

Array of contact objects

data[].iduuidrequired

Unique contact identifier

data[].phone_numberstringrequired

Contact canonical E.164 phone digits

data[].display_namestringrequired

Computed display name with phone formatting fallback

data[].first_namestringoptional

Contact first name

data[].last_namestring|nulloptional

Contact last name

data[].emailstring|nulloptional

Validated lowercase email

data[].addressstring|nulloptional

Street address or office location

data[].companystring|nulloptional

Company name

data[].citystring|nulloptional

City

data[].statestring|nulloptional

State or region

data[].countrystring|nulloptional

ISO 3166-1 alpha-2 country code

data[].sourcestring|nulloptional

Lead source

data[].platformstringrequired

Customer platform state: no_account, trial, paid, trial_ended

data[].owner_iduuid|nulloptional

Assigned user UUID

data[].marketing_opt_inbooleanrequired

Marketing opt-in status

data[].opt_in_atdatetime|nulloptional

When contact opted in

data[].opt_in_sourcestring|nulloptional

Source of marketing opt-in

data[].lifecyclestringrequired

Contact lifecycle: lead, customer, at_risk, churned

data[].lifecycle_changed_atdatetimerequired

When lifecycle status last changed

data[].user_idstringoptional

Meta BSUID (if synced)

Example:IN.23156789012345678

data[].created_atdatetimerequired

When contact was created

data[].updated_atdatetimerequired

When contact was last updated

paginationobjectrequired

Pagination metadata

pagination.totalnumberrequired

Total matching records

pagination.limitnumberrequired

Items per page

pagination.offsetnumberrequired

Current offset

Code Snippets & Examples

1	curl -X GET "https://app.chatofy.in/api/v1/contacts?limit=10" \
2	-H "Authorization: Bearer YOUR_API_KEY"

Was this endpoint guide helpful?

1	curl -X GET "https://app.chatofy.in/api/v1/contacts?limit=10" \
2	-H "Authorization: Bearer YOUR_API_KEY"

200 OKapplication/json

1	{
2	"success": true,
3	"data": [
4	{
5	"id": "b74d8c2f-dea7-4882-90b8-fddb421b19d5",
6	"phone_number": "919000000000",
7	"display_name": "Synbus Solutions",
8	"first_name": "Synbus Solutions",
9	"last_name": null,
10	"email": "[email protected]",
11	"address": "456 Bandra West, Road No 3",
12	"company": "Synbus Solutions",
13	"city": "Bengaluru",
14	"state": "Karnataka",
15	"country": "IN",
16	"source": "inbound_whatsapp",
17	"platform": "paid",
18	"owner_id": "u1111111-2222-3333-4444-555555555555",
19	"marketing_opt_in": true,
20	"opt_in_at": "2026-06-06T12:11:59+05:30",
21	"opt_in_source": "whatsapp_opt_in",
22	"lifecycle": "customer",
23	"lifecycle_changed_at": "2026-06-06T12:11:59+05:30",
24	"attributes": {},
25	"user_id": "IN.23156789012345678",
26	"username": "john_doe",
27	"parent_user_id": null,
28	"last_bsuid_sync": "2026-07-19T17:30:00+05:30",
29	"created_at": "2026-06-06T12:11:59+05:30",
30	"updated_at": "2026-06-06T13:46:05+05:30"
31	}
32	],
33	"message": "Contacts retrieved successfully",
34	"pagination": {
35	"total": 1,
36	"limit": 10,
37	"offset": 0
38	}
39	}

Chatofy API

/

Getting Started

API Resources

API v1.0 Live

Developer APIContactsList Contacts

List Contacts

Retrieves a paginated list of contacts. Supports filtering by phone, UUID, owner, and lifecycle.

GET/api/v1/contacts

Note

Each contact record includes BSUID fields (user_id, username, parent_user_id, last_bsuid_sync) for Business-Scoped User ID compatibility.

Query Parameters

6 parameters

limitnumberrequired

Max results per page (default: 100, max: 100).

offsetnumberrequired

Number of records to skip (default: 0).

phonestringrequired

Filter by phone number (e.g. +919000000000).

iduuidrequired

Filter by contact UUID.

owner_iduuid|stringrequired

Filter by owner UUID, or "unassigned".

lifecyclestringrequired

Filter by lifecycle: lead, customer, at_risk, churned.

Response Payload

200 OKapplication/json

successbooleanrequired

Whether request succeeded

messagestringrequired

Human-readable result

data[]array<object>required

Array of contact objects

data[].iduuidrequired

Unique contact identifier

data[].phone_numberstringrequired

Contact canonical E.164 phone digits

data[].display_namestringrequired

Computed display name with phone formatting fallback

data[].first_namestringoptional

Contact first name

data[].last_namestring|nulloptional

Contact last name

data[].emailstring|nulloptional

Validated lowercase email

data[].addressstring|nulloptional

Street address or office location

data[].companystring|nulloptional

Company name

data[].citystring|nulloptional

City

data[].statestring|nulloptional

State or region

data[].countrystring|nulloptional

ISO 3166-1 alpha-2 country code

data[].sourcestring|nulloptional

Lead source

data[].platformstringrequired

Customer platform state: no_account, trial, paid, trial_ended

data[].owner_iduuid|nulloptional

Assigned user UUID

data[].marketing_opt_inbooleanrequired

Marketing opt-in status

data[].opt_in_atdatetime|nulloptional

When contact opted in

data[].opt_in_sourcestring|nulloptional

Source of marketing opt-in

data[].lifecyclestringrequired

Contact lifecycle: lead, customer, at_risk, churned

data[].lifecycle_changed_atdatetimerequired

When lifecycle status last changed

data[].user_idstringoptional

Meta BSUID (if synced)

Example:IN.23156789012345678

data[].created_atdatetimerequired

When contact was created

data[].updated_atdatetimerequired

When contact was last updated

paginationobjectrequired

Pagination metadata

pagination.totalnumberrequired

Total matching records

pagination.limitnumberrequired

Items per page

pagination.offsetnumberrequired

Current offset

Code Snippets & Examples

1	curl -X GET "https://app.chatofy.in/api/v1/contacts?limit=10" \
2	-H "Authorization: Bearer YOUR_API_KEY"

Was this endpoint guide helpful?

1	curl -X GET "https://app.chatofy.in/api/v1/contacts?limit=10" \
2	-H "Authorization: Bearer YOUR_API_KEY"

200 OKapplication/json

1	{
2	"success": true,
3	"data": [
4	{
5	"id": "b74d8c2f-dea7-4882-90b8-fddb421b19d5",
6	"phone_number": "919000000000",
7	"display_name": "Synbus Solutions",
8	"first_name": "Synbus Solutions",
9	"last_name": null,
10	"email": "[email protected]",
11	"address": "456 Bandra West, Road No 3",
12	"company": "Synbus Solutions",
13	"city": "Bengaluru",
14	"state": "Karnataka",
15	"country": "IN",
16	"source": "inbound_whatsapp",
17	"platform": "paid",
18	"owner_id": "u1111111-2222-3333-4444-555555555555",
19	"marketing_opt_in": true,
20	"opt_in_at": "2026-06-06T12:11:59+05:30",
21	"opt_in_source": "whatsapp_opt_in",
22	"lifecycle": "customer",
23	"lifecycle_changed_at": "2026-06-06T12:11:59+05:30",
24	"attributes": {},
25	"user_id": "IN.23156789012345678",
26	"username": "john_doe",
27	"parent_user_id": null,
28	"last_bsuid_sync": "2026-07-19T17:30:00+05:30",
29	"created_at": "2026-06-06T12:11:59+05:30",
30	"updated_at": "2026-06-06T13:46:05+05:30"
31	}
32	],
33	"message": "Contacts retrieved successfully",
34	"pagination": {
35	"total": 1,
36	"limit": 10,
37	"offset": 0
38	}
39	}