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
Bearer authentication header of the form Bearer <token>, where <token> is your API key.
Query Parameters
The ID of the workspace
- Example: ws_1234567890
The external ID of the contact
- Example: user_12345
Response
200 Contact found successfully object
Show child attributes
Email address of the contact. This is the contact's unique identifier.
- Example: user@example.com
Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.
- Example: user_12345
Timezone of the contact
- Example: America/New_York
Preferred language of the contact
- Example: en-US
First name of the contact
- Example: John
Last name of the contact
- Example: Doe
Full name of the contact (for systems that don't have separate first/last names)
- Example: John Doe
Phone number of the contact
- Example: +15551234567
First line of address
- Example: 123 Main St
Second line of address
- Example: Apt 4B
Country of the contact
- Example: US
Postal code
- Example: 10001
State or province
- Example: NY
Job title of the contact
- Example: Software Engineer
The contact's own choice about open tracking; null means unknown.
- Available options: granted, denied, null
The contact's own choice about click tracking; null means unknown.
- Available options: granted, denied, null
When a tracking choice last changed.
Where the last tracking choice came from (api, console, import, notification_center, email_link, subscribe_form).
Custom string field 1
- Example: Premium tier
Custom string field 2
Custom string field 3
Custom string field 4
Custom string field 5
Custom number field 1
- Example: 42
Custom number field 2
Custom number field 3
Custom number field 4
Custom number field 5
Custom datetime field 1
- Example: 2023-06-01T09:00:00Z
Custom datetime field 2
Custom datetime field 3
Custom datetime field 4
Custom datetime field 5
Custom JSON field 1. Any JSON value, or null.
Custom JSON field 2. Any JSON value, or null.
Custom JSON field 3. Any JSON value, or null.
Custom JSON field 4. Any JSON value, or null.
Custom JSON field 5. Any JSON value, or null.
When the contact was created (read-only, set by server)
- Example: 2023-01-15T10:30:00Z
When the contact was last updated (read-only, set by server)
- Example: 2023-04-22T15:45:00Z
Lists the contact is subscribed to (read-only, included in GET responses only)
Show child attributes
Email address of the contact
- Example: user@example.com
ID of the list
- Example: newsletter
Name of the list
- Example: Newsletter
Subscription status
- Available options: active, pending, unsubscribed, bounced, complained
- Example: active
When the contact was subscribed to this list
- Example: 2023-01-15T10:30:00Z
When the subscription was last updated
- Example: 2023-01-15T10:30:00Z
When the subscription was deleted (null if active)
Segments the contact belongs to (read-only, included in GET responses only)
Show child attributes
Email address of the contact
- Example: user@example.com
ID of the segment
- Example: premium_users
Version of the segment computation
- Example: 1
When the contact was matched to this segment
- Example: 2023-01-15T10:30:00Z
When the segment was last computed
- Example: 2023-01-15T10:30:00Z
400 Bad request - missing parameters object
Error message
401 Unauthorized - invalid or missing authentication token object
Error message
404 Contact not found object
Error message
500 Internal server error object
Error message