List contacts
GET
Most recently updated first. Filters combine.
Scope: contacts:read.
bearerAuthheader
AuthorizationBearer <token>An organization API key, rky_live_…, created in Settings → API. Send it only from a server.
page_size?integerItems per page.
Range
1 <= value <= 100Default
50cursor?stringnext_cursor from the previous page. Use it unchanged.
Length
length <= 2048query?stringText contained in the name, phone, email or company.
Length
length <= 200tag_id?stringOnly contacts with this tag.
Format
uuidowner_user_id?stringOnly contacts this member owns.
Format
uuidlifecycle_stage?stringOnly contacts at this stage.
Value in
"subscriber""lead""marketing_qualified""sales_qualified""opportunity""customer""evangelist""other"channel?stringOnly contacts reachable on this channel.
Value in
"whatsapp""instagram""messenger"Success.
application/json- response
data*array<>next_cursor*|Pass as cursor for the next page; null on the last page.
curl -X GET 'https://getricky.ai/api/v1/contacts'{ "data": [ { "id": "3f6c2b1e-8d4a-4b7e-9a51-2c7d8e9f0a1b", "first_name": "Ana", "last_name": "Pérez", "primary_email": "ana.perez@example.com", "primary_phone": "+50760001234", "company": "Casa Nativa", "job_title": "Gerente de compras", "birthday": "1990-08-13", "city": "Panamá", "region": "Panamá", "country": "Panamá", "street_address": "Calle 50, Edificio Global, piso 3", "postal_code": null, "website_url": "https://example.com", "linkedin_url": null, "source": "WhatsApp", "notes": "Prefiere que la contacten por la tarde.", "owner_user_id": "2d4f6a8c-1b3d-4e5f-8a7b-9c0d1e2f3a4b", "lead_status": "new", "lifecycle_stage": "customer", "custom_values": { "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d": "Albrook Mall" }, "identities": [ { "id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "channel_type": "whatsapp", "external_id": "50760001234", "display_name": "Ana Pérez", "username": null } ], "tags": [ { "id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f", "name": "Cliente frecuente", "color": "gray" } ], "last_activity_at": "2026-10-14T15:30:00.000Z", "last_activity_preview": "¿Ya están mis lentes?", "last_conversation_id": "9b2e4c61-7a3f-4d18-b5c2-6e0f1a2b3c4d", "updated_at": "2026-10-14T15:30:00.000Z" } ], "next_cursor": "string"}