Contacts

Get a contact by external ID

GET https://demo.notifuse.com/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.

Authorizations

Authorization string header required

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Query Parameters

workspace_id string required

The ID of the workspace

Example ws_1234567890
external_id string required

The external ID of the contact

Example user_12345

Response

200 Contact found successfully object
contact object
Show 42 child attributes Hide 42 child attributes
email string<email> required

Email address of the contact. This is the contact's unique identifier.

Example user@example.com
external_id string | null

Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.

Example user_12345
timezone string | null

Timezone of the contact

Example America/New_York
language string | null

Preferred language of the contact

Example en-US
first_name string | null

First name of the contact

Example John
last_name string | null

Last name of the contact

Example Doe
full_name string | null

Full name of the contact (for systems that don't have separate first/last names)

Example John Doe
phone string | null

Phone number of the contact

Example +15551234567
address_line_1 string | null

First line of address

Example 123 Main St
address_line_2 string | null

Second line of address

Example Apt 4B
country string | null

Country of the contact

Example US
postcode string | null

Postal code

Example 10001
state string | null

State or province

Example NY
job_title string | null

Job title of the contact

Example Software Engineer
tracking_opens_consent string | null

The contact's own choice about open tracking; null means unknown.

Options granted, denied, null
tracking_clicks_consent string | null

The contact's own choice about click tracking; null means unknown.

Options granted, denied, null
tracking_consent_updated_at string<date-time> | null

When a tracking choice last changed.

tracking_consent_source string | null

Where the last tracking choice came from (api, console, import, notification_center, email_link, subscribe_form).

custom_string_1 string | null

Custom string field 1

Example Premium tier
custom_string_2 string | null

Custom string field 2

custom_string_3 string | null

Custom string field 3

custom_string_4 string | null

Custom string field 4

custom_string_5 string | null

Custom string field 5

custom_number_1 number<float> | null

Custom number field 1

Example 42
custom_number_2 number<float> | null

Custom number field 2

custom_number_3 number<float> | null

Custom number field 3

custom_number_4 number<float> | null

Custom number field 4

custom_number_5 number<float> | null

Custom number field 5

custom_datetime_1 string<date-time> | null

Custom datetime field 1

Example 2023-06-01T09:00:00Z
custom_datetime_2 string<date-time> | null

Custom datetime field 2

custom_datetime_3 string<date-time> | null

Custom datetime field 3

custom_datetime_4 string<date-time> | null

Custom datetime field 4

custom_datetime_5 string<date-time> | null

Custom datetime field 5

custom_json_1 any

Custom JSON field 1. Any JSON value, or null.

custom_json_2 any

Custom JSON field 2. Any JSON value, or null.

custom_json_3 any

Custom JSON field 3. Any JSON value, or null.

custom_json_4 any

Custom JSON field 4. Any JSON value, or null.

custom_json_5 any

Custom JSON field 5. Any JSON value, or null.

created_at string<date-time> read-only

When the contact was created (read-only, set by server)

Example 2023-01-15T10:30:00Z
updated_at string<date-time> read-only

When the contact was last updated (read-only, set by server)

Example 2023-04-22T15:45:00Z
contact_lists object[] read-only

Lists the contact is subscribed to (read-only, included in GET responses only)

Show 7 child attributes Hide 7 child attributes
email string<email>

Email address of the contact

Example user@example.com
list_id string

ID of the list

Example newsletter
list_name string

Name of the list

Example Newsletter
status string

Subscription status

Options active, pending, unsubscribed, bounced, complained Example active
created_at string<date-time>

When the contact was subscribed to this list

Example 2023-01-15T10:30:00Z
updated_at string<date-time>

When the subscription was last updated

Example 2023-01-15T10:30:00Z
deleted_at string<date-time> | null

When the subscription was deleted (null if active)

contact_segments object[] read-only

Segments the contact belongs to (read-only, included in GET responses only)

Show 5 child attributes Hide 5 child attributes
email string<email>

Email address of the contact

Example user@example.com
segment_id string

ID of the segment

Example premium_users
version integer<int64>

Version of the segment computation

Example 1
matched_at string<date-time>

When the contact was matched to this segment

Example 2023-01-15T10:30:00Z
computed_at string<date-time>

When the segment was last computed

Example 2023-01-15T10:30:00Z
400 Bad request - missing parameters object
error string required

Error message

401 Unauthorized - invalid or missing authentication token object
error string required

Error message

404 Contact not found object
error string required

Error message

500 Internal server error object
error string required

Error message