Get a contact by external ID

curl --request GET \
  --url https://{notifuseDomain}/api/contacts.getByExternalID \
  --header 'Authorization: Bearer <token>'

{
  "contact": {
    "email": "[email protected]",
    "external_id": "user_12345",
    "timezone": "America/New_York",
    "language": "en-US",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "phone": "+15551234567",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "postcode": "10001",
    "state": "NY",
    "job_title": "Software Engineer",
    "custom_string_1": "Premium tier",
    "custom_string_2": "<string>",
    "custom_string_3": "<string>",
    "custom_string_4": "<string>",
    "custom_string_5": "<string>",
    "custom_number_1": 42,
    "custom_number_2": 123,
    "custom_number_3": 123,
    "custom_number_4": 123,
    "custom_number_5": 123,
    "custom_datetime_1": "2023-06-01T09:00:00Z",
    "custom_datetime_2": "2023-11-07T05:31:56Z",
    "custom_datetime_3": "2023-11-07T05:31:56Z",
    "custom_datetime_4": "2023-11-07T05:31:56Z",
    "custom_datetime_5": "2023-11-07T05:31:56Z",
    "custom_json_1": {
      "preferences": {
        "theme": "dark",
        "notifications": true
      }
    },
    "custom_json_2": {},
    "custom_json_3": {},
    "custom_json_4": {},
    "custom_json_5": {},
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-04-22T15:45:00Z",
    "contact_lists": [
      {
        "email": "[email protected]",
        "list_id": "newsletter",
        "list_name": "Newsletter",
        "status": "active",
        "created_at": "2023-01-15T10:30:00Z",
        "updated_at": "2023-01-15T10:30:00Z",
        "deleted_at": null
      }
    ],
    "contact_segments": [
      {
        "email": "[email protected]",
        "segment_id": "premium_users",
        "version": 1,
        "matched_at": "2023-01-15T10:30:00Z",
        "computed_at": "2023-01-15T10:30:00Z"
      }
    ]
  }
}

GET

api

contacts.getByExternalID

Get a contact by external ID

curl --request GET \
  --url https://{notifuseDomain}/api/contacts.getByExternalID \
  --header 'Authorization: Bearer <token>'

{
  "contact": {
    "email": "[email protected]",
    "external_id": "user_12345",
    "timezone": "America/New_York",
    "language": "en-US",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "phone": "+15551234567",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "postcode": "10001",
    "state": "NY",
    "job_title": "Software Engineer",
    "custom_string_1": "Premium tier",
    "custom_string_2": "<string>",
    "custom_string_3": "<string>",
    "custom_string_4": "<string>",
    "custom_string_5": "<string>",
    "custom_number_1": 42,
    "custom_number_2": 123,
    "custom_number_3": 123,
    "custom_number_4": 123,
    "custom_number_5": 123,
    "custom_datetime_1": "2023-06-01T09:00:00Z",
    "custom_datetime_2": "2023-11-07T05:31:56Z",
    "custom_datetime_3": "2023-11-07T05:31:56Z",
    "custom_datetime_4": "2023-11-07T05:31:56Z",
    "custom_datetime_5": "2023-11-07T05:31:56Z",
    "custom_json_1": {
      "preferences": {
        "theme": "dark",
        "notifications": true
      }
    },
    "custom_json_2": {},
    "custom_json_3": {},
    "custom_json_4": {},
    "custom_json_5": {},
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-04-22T15:45:00Z",
    "contact_lists": [
      {
        "email": "[email protected]",
        "list_id": "newsletter",
        "list_name": "Newsletter",
        "status": "active",
        "created_at": "2023-01-15T10:30:00Z",
        "updated_at": "2023-01-15T10:30:00Z",
        "deleted_at": null
      }
    ],
    "contact_segments": [
      {
        "email": "[email protected]",
        "segment_id": "premium_users",
        "version": 1,
        "matched_at": "2023-01-15T10:30:00Z",
        "computed_at": "2023-01-15T10:30:00Z"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

API token for authentication

Query Parameters

workspace_id

string

required

The ID of the workspace

external_id

string

required

The external ID of the contact

Response

Contact found successfully

contact

object

Show child attributes

contact.email

string<email>

required

Email address of the contact

Example:

"[email protected]"

contact.external_id

string | null

External identifier for the contact

Example:

"user_12345"

contact.timezone

string | null

Timezone of the contact

Example:

"America/New_York"

contact.language

string | null

Preferred language of the contact

Example:

"en-US"

contact.first_name

string | null

First name of the contact

Example:

"John"

contact.last_name

string | null

Last name of the contact

Example:

"Doe"

contact.full_name

string | null

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

Example:

"John Doe"

contact.phone

string | null

Phone number of the contact

Example:

"+15551234567"

contact.address_line_1

string | null

First line of address

Example:

"123 Main St"

contact.address_line_2

string | null

Second line of address

Example:

"Apt 4B"

contact.country

string | null

Country of the contact

Example:

"US"

contact.postcode

string | null

Postal code

Example:

"10001"

contact.state

string | null

State or province

Example:

"NY"

contact.job_title

string | null

Job title of the contact

Example:

"Software Engineer"

contact.custom_string_1

string | null

Custom string field 1

Example:

"Premium tier"

contact.custom_string_2

string | null

Custom string field 2

contact.custom_string_3

string | null

Custom string field 3

contact.custom_string_4

string | null

Custom string field 4

contact.custom_string_5

string | null

Custom string field 5

contact.custom_number_1

number<float> | null

Custom number field 1

Example:

42

contact.custom_number_2

number<float> | null

Custom number field 2

contact.custom_number_3

number<float> | null

Custom number field 3

contact.custom_number_4

number<float> | null

Custom number field 4

contact.custom_number_5

number<float> | null

Custom number field 5

contact.custom_datetime_1

string<date-time> | null

Custom datetime field 1

Example:

"2023-06-01T09:00:00Z"

contact.custom_datetime_2

string<date-time> | null

Custom datetime field 2

contact.custom_datetime_3

string<date-time> | null

Custom datetime field 3

contact.custom_datetime_4

string<date-time> | null

Custom datetime field 4

contact.custom_datetime_5

string<date-time> | null

Custom datetime field 5

contact.custom_json_1

object

Custom JSON field 1

Example:

{
  "preferences": { "theme": "dark", "notifications": true }
}

contact.custom_json_2

object

Custom JSON field 2

contact.custom_json_3

object

Custom JSON field 3

contact.custom_json_4

object

Custom JSON field 4

contact.custom_json_5

object

Custom JSON field 5

contact.created_at

string<date-time>

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

Example:

"2023-01-15T10:30:00Z"

contact.updated_at

string<date-time>

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

Example:

"2023-04-22T15:45:00Z"

contact.contact_lists

object[]

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

Show child attributes

contact.contact_lists.email

string<email>

Email address of the contact

Example:

"[email protected]"

contact.contact_lists.list_id

string

ID of the list

Example:

"newsletter"

contact.contact_lists.list_name

string

Name of the list

Example:

"Newsletter"

contact.contact_lists.status

enum<string>

Subscription status

Available options:

active,

pending,

unsubscribed,

bounced,

complained

Example:

"active"

contact.contact_lists.created_at

string<date-time>

When the contact was subscribed to this list

Example:

"2023-01-15T10:30:00Z"

contact.contact_lists.updated_at

string<date-time>

When the subscription was last updated

Example:

"2023-01-15T10:30:00Z"

contact.contact_lists.deleted_at

string<date-time> | null

When the subscription was deleted (null if active)

Example:

null

Example:

[
  {
    "email": "[email protected]",
    "list_id": "newsletter",
    "list_name": "Newsletter",
    "status": "active",
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-01-15T10:30:00Z",
    "deleted_at": null
  }
]

contact.contact_segments

object[]

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

Show child attributes

contact.contact_segments.email

string<email>

Email address of the contact

Example:

"[email protected]"

contact.contact_segments.segment_id

string

ID of the segment

Example:

"premium_users"

contact.contact_segments.version

integer<int64>

Version of the segment computation

Example:

1

contact.contact_segments.matched_at

string<date-time>

When the contact was matched to this segment

Example:

"2023-01-15T10:30:00Z"

contact.contact_segments.computed_at

string<date-time>

When the segment was last computed

Example:

"2023-01-15T10:30:00Z"

Get a contact by email address Batch import contacts

⌘I

Transactional

Contacts

Lists

Custom Events

Broadcasts

Templates

Webhooks

Get a contact by external ID

Authorizations

Query Parameters

Response