> ## Documentation Index > Fetch the complete documentation index at: https://developers.heymarket.com/llms.txt > Use this file to discover all available pages before exploring further. # Get contact (v2) > Get a contact by UUID. Use this endpoint when you are working with v2 UUID-based contact identifiers. ## OpenAPI ````yaml api-reference/openapi/heymarket-openapi-3.1.2.yaml GET /v2/contact/{contactID} openapi: 3.1.2 info: contact: email: help@heymarket.com name: API Support url: https://heymarket.com description: > Welcome to Heymarket’s API! Many users access Heymarket via the web app, mobile apps, or one of the out-of-the-box platform integrations. However, much of Heymarket’s functionality can also be accessed via the API. The flexibility and scalability of the API makes it an excellent choice for integrating Heymarket into existing applications. This documentation provides details on: available authentication methods, endpoints that are available and error message information. If you want to get right to the action, download the collection to start performing calls from Postman or other similar software. All valid HTTP request and response bodies are encoded in JSON. For security purposes API requests must be made over HTTPS. Calls made over plain HTTP or without authentication will fail. Base URL: https://api.heymarket.com # Rate Limit The Heymarket API has a rate limit of 500 requests per minute. Exceeding the rate limit will result in responses with a 429 status code. # Request IDs Each API request has an associated request identifier. You can find this value in the response headers, under `X-Request-Id`. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution. # Webhooks You can read more about [getting started with webhooks](https://help.heymarket.com/hc/en-us/articles/4416494130701-Getting-Started-with-Webhooks) from our articles collection. # Additional Admin APIs For more information about additional Admin APIs, please contact us at . license: name: Heymarket url: https://heymarket.com/legal termsOfService: https://heymarket.com/tos title: Heymarket API version: '1.0' servers: - url: https://api.heymarket.com security: [] tags: - name: Inboxes description: > The `Inbox` object represents a read only view of the team's inbox(es) in Heymarket. Any API requests that deal with message sending or scheduling will require an inbox ID as a parameter. #### The Inbox object | Attributes | Description | | ---------- | --------------------------------------------------------------------- | | `id` | Unique identifier for the object | | `name` | Name of the inbox | | `team` | Unique identifier for your team | | `members` | Unique identifier for your team members who have access to the inbox | | `phones` | Heymarket phone number(s) associated with the inbox | - name: Users description: > The `User` object represents a team user in Heymarket. #### The User object | Attributes | Description | | ------------------ | ------------------------------------------------------------- | | `id` | Unique identifier for the object | | `name` | Name of the user | | `email` | Email address of the user | | `phone` | Phone number of the user | | `role_id` | Unique identifier of the role of the user within the team | | `team_id` | Unique identifier for the team the user belongs to | | `created_at` | Creation date of the team user | | `updated_at` | Last updated date of the team user | | `user_created_at` | Creation date of the base user | | `user_updated_at` | Last updated date of the base user | - name: Team description: > The `Team` object represents a read only view of the team in Heymarket. #### The Team object | Attributes | Description | | ---------- | --------------------------------------------------------------------- | | `id` | Unique identifier for the object | | `name` | Name of the team | | `list_size` | List size limit | `members` | Unique identifiers for the users who have access to the team as well as their role within the team| - name: Contacts description: > The `Contact` object is a Heymarket contact. The contacts in Heymarket are used for storing information such as name, phone number, and email address. Contacts also store custom fields which can be used for search, list creation, and merge tokens while sending messages. #### The Contact object | Attributes | Description | | ------------------ | -------------------------------------------------------------------------- | | `id` | Unique identifier for the object | | `display_name` | Display name, usually a combination of first and last name | | `first` | First name | | `last` | Last name | | `email` | Email address | | `phone` | Phone number | | `custom` | Custom fields with value if present, only lists contact field ID and value | | `team_id` | Unique identifier for your Heymarket team | | `creator_id` | Unique identifier for the user who created the contact, same as the member ID returned by Get Inboxes | | `shared` | Boolean value for whether the contact is shared with team members | | `created` | Creation date | | `updated` | Last updated date | | `rev` | Last revision number | | `op` | Operation performed | | `assigned_user_id` | Contact Owner ID | | `tags` | Array of up to 5 `tag_id` objects | | `is_opted_out` | Is this contact opted out of messaging? | - name: Conversations description: The `Conversation` object represents a messaging thread in Heymarket. - name: Lists description: > The `List` object in Heymarket is used for organizing multiple phone numbers. You can send a single message to a list, the contacts will never see each other and can reply privately. Lists are also used as a source of contacts for your campaigns. #### The List object | Attributes | Description | | ------------ | --------------------------------------------------- | | `id` | Unique identifier for the object | | `name` | List name | | `local_id` | Client provided unique identifier for the object | | `targets` | Object containing multiple `ListTarget` objects | | `team_id` | Unique identifier for your Heymarket team | | `creator_id` | Unique identifier for the user who created the list | | `shared` | If the list is shared with team members | | `created` | Creation date | | `updated` | Last updated date | | `rev` | Last revision number | | `op` | Operation performed | The `targets` object is a light weight representation of a contact. `phone` is used as a key and it has name fields as optional attributes which will be used as a merge token during message sending if there is no real Heymarket contact available for this phone number. #### The ListTarget object | Attributes | Description | | ---------- | ----------------------- | | `f` | First name (if available) | | `l` | Last name (if available) | - name: Templates description: > The `Template` object in Heymarket is a pre-defined message with text and media. Templates can also contain merge tokens which will insert the appropriate custom field values when sending the message. The main body of the template is stored in the `content` attribute. #### The Template object | Attributes | Description | | ------------ | --------------------------------------------------- | | `id` | Unique identifier for the object | | `name` | Template name | | `local_id` | Client provided unique identifier for the object | | `content` | Object representing template content | | `team_id` | Unique identifier for your Heymarket team | | `creator_id` | Unique identifier for the user who created the template, same as the member ID returned by Get Inboxes | | `shared` | If the template is shared with team members | | `created` | Creation date | | `updated` | Last updated date | | `rev` | Last revision number | | `op` | Operation performed | #### The Content object | Attributes | Description | | ---------- | ------------------------------- | | `text` | Message text | | `gallery` | Array of `GalleryEntry` objects | - name: Messages description: > The `Messages` API is a powerful Heymarket feature. With it you can send messages to individual contacts or a list of contacts. It has all the features of Heymarket's native clients, including sending messages from a template, sending media, and inserting merge tokens. - name: Schedule description: > With the `Scheduling` API you can schedule a message to be sent to an individual contact or to a list. - name: Surveys description: > Ask your customers a set of standardized questions to quickly understand their experience with your company. - name: Tags description: | The `Tag` object in Heymarket. #### The Tag object | Attributes | Description | | ------------ | --------------------------------------------------- | | `id` | Unique identifier for the object | | `tag` | Tag name | | `color` | Color | | `team_id` | Unique identifier for your Heymarket team | | `created` | Creation date | | `updated` | Last updated date | | `rev` | Last revision number | - name: Links description: > The `Link` object represents a tracked short URL owned by your team. Link tracking must be enabled for your team to use these endpoints. Requests from teams without the link tracking feature return `403` with the message `link_tracking_not_available`. All link operations are scoped to the team identified by your API credentials — links belonging to other teams cannot be read, updated, or deleted, and lookups for them return `404`. #### The Link object | Attributes | Description | | ---------- | ----------- | | `id` | Unique identifier for the object | | `short_code` | Code segment of the short URL | | `short_url` | Full short URL to include in messages | | `original_url` | Destination URL the short link redirects to | | `team_id` | Unique identifier for your team | | `target` | Target the link is attributed to (optional) | | `conversation_id` | Conversation the link is attributed to (optional) | | `broadcast_id` | Broadcast the link is attributed to (optional) | | `campaign_step_id` | Campaign step the link is attributed to (optional) | | `template_id` | Template the link is attributed to (optional) | | `last_visited_at` | Timestamp of the most recent click (optional) | | `created_at` | Creation date | - name: Webhooks description: Events Heymarket sends to webhook URLs configured for a team. paths: /v2/contact/{contactID}: get: tags: - Contacts summary: Retrieve Contact (V2) description: Retrieve a contact by their UUID. operationId: v2GetContact parameters: - description: Contact UUID in: path name: contactID required: true schema: type: string responses: '200': description: Contact content: application/json: schema: $ref: '#/components/schemas/doc.Contact' '400': description: bad_data content: application/json: schema: type: string '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/TooManyRequestsError' default: $ref: '#/components/responses/DefaultServerError' security: - ApiSecretJwtAuth: [] - LegacyApiKeyAuth: [] components: schemas: doc.Contact: properties: avatar: type: string created: type: string creator_id: type: integer custom: type: object display_name: type: string email: type: string external_id: type: string external_ref: type: string first: type: string id: type: integer inbox_id: type: integer last: type: string note: items: $ref: '#/components/schemas/doc.ContactNote' type: array op: type: string parent_id: type: integer phone: type: string rev: type: integer shared: type: boolean team_id: type: integer type: type: string updated: type: string assigned_user_id: type: integer tags: type: array items: {} type: object doc.ContactNote: properties: date: type: string id: type: string name: type: string text: type: string user_id: type: integer type: object responses: UnauthorizedError: description: Authentication credentials were missing or invalid. content: text/plain: schema: type: string examples: response: value: Unauthorized TooManyRequestsError: description: The request exceeded the API rate limit. content: text/plain: schema: type: string examples: response: value: too many requests DefaultServerError: description: Unexpected server error. content: text/plain: schema: type: string examples: response: value: error securitySchemes: ApiSecretJwtAuth: type: http scheme: bearer bearerFormat: JWT description: >- Recommended authentication for new integrations. Generate a short-lived JWT from your API Secret ID and API Secret Key, then pass the signed JWT as a bearer token in the `Authorization` header. API Secret credentials are available in the Heymarket app under Settings > Integrations > API. The Secret Key is shown only when it is generated, so copy and store it securely before closing the dialog. Use the following JWT values: ```json { "alg": "HS256", "typ": "JWT" } ``` ```text { "iss": "YOUR_API_SECRET_ID", "iat": CURRENT_UNIX_TIMESTAMP } ``` Replace `CURRENT_UNIX_TIMESTAMP` with the current Unix timestamp in seconds when generating the token. Sign the JWT with HMAC-SHA256 using this signing secret: ```text YOUR_API_SECRET_ID||YOUR_API_SECRET_KEY ``` Send the signed JWT as a bearer token: ```text Authorization: Bearer YOUR_SIGNED_JWT ``` Tokens expire 5 minutes after the `iat` timestamp. Generate a new JWT per request, or cache it briefly for less than 5 minutes. Generate JWTs only from trusted server-side code; do not expose the API Secret Key in browser, mobile, or other client-side code. LegacyApiKeyAuth: type: http scheme: bearer bearerFormat: Team API key description: >- Legacy authentication for existing integrations. Provide the Heymarket team API key as a bearer token in the `Authorization` header. ```text Authorization: Bearer YOUR_API_KEY ``` API key authentication is planned for deprecation. New integrations should use API Secret JWT authentication. ````