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
custom_fields
Description
Custom contact field values keyed by field name.
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/HR_id_example_organization_id/contacts \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "limit=25"

Example response

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

Create a contact

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

Use this endpoint to create one contact under an organization. At least one of name, email, or phone_number is required. email must be a valid address format (for example [email protected] or [email protected]). phone_number examples accepted and normalized include +14155550199, 415-555-0199, (415) 555-0199, and 1-415-555-0199.

Request body fields:

Name
name
Description
Optional display name for the contact.
Name
email
Description
Optional primary email address for the contact. Example formats: [email protected], [email protected].
Name
phone_number
Description
Optional primary phone number for the contact. Example formats: +14155550199, 415-555-0199, (415) 555-0199, 1-415-555-0199.
Name
company_id
Description
Optional encoded company ID. If provided, the company must belong to the same organization.
Name
custom_fields
Description
Optional custom contact field values keyed by field name.
Name
company_role
Description
Optional role/title of the contact relative to the company.

Create one contact

curl -X POST https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/contacts \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hal Jordan",
    "email": "[email protected]",
    "phone_number": "+14155550199",
    "company_id": "HR_id_example_company_id",
    "custom_fields": {
      "notes": "Primary billing contact"
    },
    "company_role": "Controller"
  }'

Example response

{
  "contact_id": "HR_id_example_contact_id",
  "name": "Hal Jordan",
  "email": "[email protected]",
  "phone_number": "+14155550199",
  "created_at": "2026-05-15T15:34:12.000000Z",
  "company_id": "HR_id_example_company_id",
  "custom_fields": {
    "notes": "Primary billing contact"
  },
  "company_role": "Controller"
}

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/HR_id_example_organization_id/contacts/HR_id_example_contact_id \
  -H "X-API-KEY: your-api-key"

Example response

{
    "contact_id": "HR_id_example_contact_id",
    "name": "Diana Prince",
    "email": "[email protected]",
    "phone_number": "513-867-5309",
    "created_at": "2026-03-12T00:32:13.782565Z",
    "company_id": "HR_id_example_company_id",
    "custom_fields": {
      "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/HR_id_example_organization_id/contacts/HR_id_example_contact_id/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": "HR_id_example_conversation_id",
        "start_at": "2026-03-12T00:32:13.790998Z",
        "last_activity_at": "2026-03-12T00:32:13.797290Z",
        "folder": "primary",
        "is_read": true,
        "contact_id": "HR_id_example_contact_id"
    }
  ],
  "pagination": {
    "limit": 50,
    "cursor": null,
    "next_cursor": null,
    "has_more": false
  }
}