--- title: "Get a contact by external ID" method: GET path: "/api/contacts.getByExternalID" --- # Get a contact by external ID `GET /api/contacts.getByExternalID` Retrieves a contact by their external ID within a specific workspace. The response always includes the contact's list subscriptions with their status (active, pending, unsubscribed, bounced, complained). Note that `external_id` is not unique — if several contacts share the same external ID, only one of them is returned (which one is not defined). Contacts are uniquely identified by email address. ## Query parameters - `workspace_id` string, required - `external_id` string, required ## Response `200` Contact found successfully - object - `contact` Contact - `email` string, email, required — Email address of the contact. This is the contact's unique identifier. - `external_id` string, nullable — Identifier for the contact in your own system. Not unique — several contacts may share the same external_id. - `timezone` string, nullable — Timezone of the contact - `language` string, nullable — Preferred language of the contact - `first_name` string, nullable — First name of the contact - `last_name` string, nullable — Last name of the contact - `full_name` string, nullable — Full name of the contact (for systems that don't have separate first/last names) - `phone` string, nullable — Phone number of the contact - `address_line_1` string, nullable — First line of address - `address_line_2` string, nullable — Second line of address - `country` string, nullable — Country of the contact - `postcode` string, nullable — Postal code - `state` string, nullable — State or province - `job_title` string, nullable — Job title of the contact - `custom_string_1` string, nullable — Custom string field 1 - `custom_string_2` string, nullable — Custom string field 2 - `custom_string_3` string, nullable — Custom string field 3 - `custom_string_4` string, nullable — Custom string field 4 - `custom_string_5` string, nullable — Custom string field 5 - `custom_number_1` number, float, nullable — Custom number field 1 - `custom_number_2` number, float, nullable — Custom number field 2 - `custom_number_3` number, float, nullable — Custom number field 3 - `custom_number_4` number, float, nullable — Custom number field 4 - `custom_number_5` number, float, nullable — Custom number field 5 - `custom_datetime_1` string, date-time, nullable — Custom datetime field 1 - `custom_datetime_2` string, date-time, nullable — Custom datetime field 2 - `custom_datetime_3` string, date-time, nullable — Custom datetime field 3 - `custom_datetime_4` string, date-time, nullable — Custom datetime field 4 - `custom_datetime_5` string, date-time, nullable — Custom datetime field 5 - `custom_json_1` object, nullable — Custom JSON field 1 - `custom_json_2` object, nullable — Custom JSON field 2 - `custom_json_3` object, nullable — Custom JSON field 3 - `custom_json_4` object, nullable — Custom JSON field 4 - `custom_json_5` object, nullable — Custom JSON field 5 - `created_at` string, date-time — When the contact was created (read-only, set by server) - `updated_at` string, date-time — When the contact was last updated (read-only, set by server) - `contact_lists` ContactList[] — Lists the contact is subscribed to (read-only, included in GET responses only) - `email` string, email — Email address of the contact - `list_id` string — ID of the list - `list_name` string — Name of the list - `status` 'active' | 'pending' | 'unsubscribed' | 'bounced' | 'complained' — Subscription status - `created_at` string, date-time — When the contact was subscribed to this list - `updated_at` string, date-time — When the subscription was last updated - `deleted_at` string, date-time, nullable — When the subscription was deleted (null if active) - `contact_segments` ContactSegment[] — Segments the contact belongs to (read-only, included in GET responses only) - `email` string, email — Email address of the contact - `segment_id` string — ID of the segment - `version` integer — Version of the segment computation - `matched_at` string, date-time — When the contact was matched to this segment - `computed_at` string, date-time — When the segment was last computed ## Other responses - `400` — Bad request - missing parameters - `401` — Unauthorized - invalid or missing authentication token - `404` — Contact not found - `500` — Internal server error ## Changes - **2025-12-02** `c9edbbd76e08` — 4 info - the response optional property `contact/contact_lists` became read-only for the status `200` - the response optional property `contact/contact_segments` became read-only for the status `200` - the response optional property `contact/created_at` became read-only for the status `200` - the response optional property `contact/updated_at` became read-only for the status `200` - **2025-12-01** `bca4a43d9d46` — 2 info - added the optional property `contact/contact_segments` to the response with the `200` status - added the optional property `contact/full_name` to the response with the `200` status - **2025-11-29** `c39acad12e49` — 3 warning - removed the optional property `contact/last_order_at` from the response with the `200` status - removed the optional property `contact/lifetime_value` from the response with the `200` status - removed the optional property `contact/orders_count` from the response with the `200` status - **2025-11-01** `6d2b86adbdc3` — 1 info - added the optional property `contact/contact_lists` to the response with the `200` status - **2025-08-24** `384ae1bf1437` — 1 info - endpoint added [Change history](https://skmtc.dev/pierre-b/apis/notifuse-api/changes/api/contacts.getByExternalID/get.md) --- [API](https://skmtc.dev/pierre-b/apis/notifuse-api.md) · [All operations](https://skmtc.dev/pierre-b/apis/notifuse-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pierre-b/notifuse-api/revisions/d26605f2fc47/schema)