Contacts

Use the contacts endpoint to read the individual customers that emailed into your organization and then jump from a contact into that contact's conversations.

List contacts

GET /api/v2/organizations/{organization_id}/contacts

Use the organization_id returned by the organizations endpoint. This endpoint supports limit and cursor.

Key response fields:

Name
contact_id
Description
The contact identifier used for the contact detail and contact conversations endpoints.
Name
name
Description
The display name for the contact.
Name
email
Description
The primary email address when available.
Name
phone_number
Description
The primary phone number when available.
Name
created_at
Description
When the contact was created.
Name
company_id
Description
The company identifier when the contact is linked to a company.
Name
notes
Description
Additional notes for the contact.
Name
company_role
Description
The contact's role or relationship to the linked company.

List contacts

curl -G https://api.hyperrep.ai/api/v2/organizations/gAAAAABexampleOrganizationIdReturnedByApi7mN4qP2xLs9dV5kTr8cY1hJ6uW3/contacts \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "limit=25"

Example response

{
  "data": [
    {
      "contact_id": "gAAAAABexampleContactIdReturnedByApi4pQ8xLm2sV7kRt1cN5hY9uJ3dF6",
      "name": "Diana Prince",
      "email": "[email protected]",
      "phone_number": "513-867-5309",
      "created_at": "2026-03-12T00:32:13.782565Z",
      "company_id": "gAAAAABexampleCompanyIdReturnedByApi6vT2mQ9xLs4dK7pNc1hY5uJ8rF3",
      "notes": "Prefers SMS",
      "company_role": "Facilities Manager"
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": null,
    "has_more": false
  }
}

Get a contact

GET /api/v2/organizations/{organization_id}/contacts/{contact_id}

Use the contact_id returned by the contacts list endpoint.

This endpoint returns one contact in the same canonical contact shape used by the list endpoint.

Get one contact

curl https://api.hyperrep.ai/api/v2/organizations/gAAAAABexampleOrganizationIdReturnedByApi7mN4qP2xLs9dV5kTr8cY1hJ6uW3/contacts/gAAAAABexampleContactIdReturnedByApi4pQ8xLm2sV7kRt1cN5hY9uJ3dF6 \
  -H "X-API-KEY: your-api-key"

Example response

{
    "contact_id": "gAAAAABexampleContactIdReturnedByApi4pQ8xLm2sV7kRt1cN5hY9uJ3dF6",
    "name": "Diana Prince",
    "email": "[email protected]",
    "phone_number": "513-867-5309",
    "created_at": "2026-03-12T00:32:13.782565Z",
    "company_id": "gAAAAABexampleCompanyIdReturnedByApi6vT2mQ9xLs4dK7pNc1hY5uJ8rF3",
    "notes": "Prefers SMS",
    "company_role": "Facilities Manager"
  }

List a contact's conversations

GET /api/v2/organizations/{organization_id}/contacts/{contact_id}/conversations

Use this endpoint when you already know the contact you want to inspect and need their conversations directly. start_date and end_date are optional — omit them to return all conversations for the contact. A missing contact_id returns 404.

The response includes paginated conversation summaries with fields such as conversation_id, start_at, last_activity_at, folder, and is_read. To gain further insights on these conversations, use the conversation_id values to fetch the full conversation details.

List conversations for one contact

curl -G https://api.hyperrep.ai/api/v2/organizations/gAAAAABexampleOrganizationIdReturnedByApi7mN4qP2xLs9dV5kTr8cY1hJ6uW3/contacts/gAAAAABexampleContactIdReturnedByApi4pQ8xLm2sV7kRt1cN5hY9uJ3dF6/conversations \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "limit=25" \
  --data-urlencode "start_date=2026-04-01T00:00:00Z" \
  --data-urlencode "end_date=2026-04-30T23:59:59Z"

Example response

{
  "data": [
    {
        "conversation_id": "gAAAAABexampleConversationIdReturnedByApi8kP3xLs7dV2mTr5cN9hY1uJ4",
        "start_at": "2026-03-12T00:32:13.790998Z",
        "last_activity_at": "2026-03-12T00:32:13.797290Z",
        "folder": "primary",
        "is_read": true,
        "contact_id": "gAAAAABexampleContactIdReturnedByApi4pQ8xLm2sV7kRt1cN5hY9uJ3dF6"
    }
  ],
  "pagination": {
    "limit": 50,
    "cursor": null,
    "next_cursor": null,
    "has_more": false
  }
}