Export profile data

Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom ID.

The Profiles API allows you to export profiles data. Use this endpoint to:

Export profile native attributes
Export profile custom attributes
Export profile identifiers
Export profile events

API Description

Export

post

Create a request to export profile data.

Authorizations

Header parameters

X-Batch-ProjectstringRequired

The unique project key, identifying a project on the Batch platform

Example: project_0664hxvwffvbpn278gxdyhsadddqgna6

Body

any ofOptional

Responses

202

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and a request id. Once you get your request id, you can use it to check the export request status with the export view API endpoint.

application/json

400

The request is malformed

application/json

401

The Rest API Key is not valid for this project

application/json

429

Too Many Requests

application/json

500

Unexpected error

application/json

503

Batch's services are under maintenance. Please try again later

application/json

post

/profiles/export

POST /2.7/profiles/export HTTP/1.1
Host: api.batch.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Batch-Project: text
Content-Type: application/json
Accept: */*
Content-Length: 183

{
  "export_type": "ATTRIBUTES",
  "attributes": [
    "$email_address",
    "$language",
    "firstname",
    "is_premium"
  ],
  "identifiers": [
    "custom_id",
    "installation_ids"
  ],
  "filter": {
    "segment": "MY-SEGMENT-CODE"
  }
}

{
  "id": "export_063bc4w4x8e363yem6wfnxc5c13c0n46"
}

Lookback

Some kind of exports are logs of detailed events that happened. Those raw events are not kept forever and will stop being available to export after a while: this is documented in the "Lookback" duration for each event kind. Providing a from parameter older than the lookback period will result in an error.

Exports that represent a snapshot of data (such as Profile Attributes) do not have this limitation.

Route

The Profile API exposes a POST endpoint that allows to create an export request:

/profiles/export

Headers and authentication

See Overview → Using Project APIs.

Profile Attributes

Use this to export custom and native attributes as well as the identifiers of your profiles.

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

{
    "export_type": "ATTRIBUTES",
    "attributes": [
        "$creation_date",
        "$email_address",
        "$email_marketing",
        "$language",
        "$last_activity",
        "$last_email_marketing_click",
        "$last_email_marketing_open",
        "$last_email_transactional_click",
        "$last_email_transactional_open",
        "$last_visit_date",
        "$phone_number",
        "$push_subscriptions",
        "$region",
        "$sms_marketing",
        "$timezone"
    ],
    "identifiers": [
        "custom_id",
        "installation_ids"
    ],
    "filter": {
        "segment": "MY-SEGMENT-CODE"
    }
}

You must specify at least one of attributes, identifiers or both in your export request.

The filter parameter is optional. Currently, you can only filter by segment. Specify the segment by providing the segment code* you want to use for this export.

*The segment code is available in two places within the Dashboard on the Segments page:

Either via the "Copy segment code" option in the dropdown menu.
Or by clicking the copy icon on the right-hand side of the modal for the specific segment.

Rate limiting with filter parameter

Please note: when the filter parameter is being passed, we apply a rate limiting of 5 requests per hour (1 new request authorised every 12 minutes), with a maximum authorised burst of 10 requests.

Export file structure

The export will contain a list of attributes. Each attribute is composed of an attribute object and an identifiers object.

Field

Description

Type

Required

attribute

Representation of an attribute object

object

identifiers

Representation of an identifiers object

object

Attribute Object

Representation of an attribute object.

Identifiers object

Represents the identifiers of the profile concerned by the event.

Field

Description

Type

Required

profile_id

Unique identifier of the profile E.g.{"profile_id":"profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v"}

string

custom_id

Custom identifier of the profile E.g.{"custom_id":"User1"}

string

installation_ids

Installation identifier of the profile. Only available on PUSH channels E.g.{"installation_ids": ["828A7D76-3D5E-49DC-A863-2465070184C9"]}

string

Export file sample

This is a sample of the content of the export file you will receive.

Example

[
  {
    "attributes": {
      "$email_address": "jane.doe@demobatch.com",
      "$email_marketing": "subscribed",
      "$language": "fr",
      "$phone_number": null,
      "$region": "FR",
      "$sms_marketing": "unsubscribed",
      "$timezone": "Europe/Paris"
    },
    "identifiers": {
      "custom_id": "User1",
      "installation_ids": ["828A7D76-3D5E-49DC-A863-2465070184C9"],
      "profile_id": "profile_1m9yqztq4w5gxs2pbkqkn8rt1agv0p9n"
    }
  },
  {
    "attributes": {
      "$email_address": "john.doe@demobatch.com",
      "$email_marketing": "subscribed",
      "$language": "fr",
      "$phone_number": null,
      "$region": "FR",
      "$sms_marketing": "unsubscribed",
      "$timezone": "Europe/Paris"
    },
    "identifiers": {
      "custom_id": "User2",
      "profile_id": "profile_3r1vczm73kzq8ebfyt72cp4nm9qd2jk6"
    }
  },
  {
    "attributes": {
      "$email_address": null,
      "$email_marketing": "unsubscribed",
      "$language": "fr",
      "$phone_number": "+33182837140",
      "$region": "FR",
      "$sms_marketing": "subscribed",
      "$timezone": "Europe/Paris"
    },
    "identifiers": {
      "profile_id": "profile_0vnyhjdkt9bs0fx1znp5a4ew8mcz21td"
    }
  }
]

Profile Events

Use this to export events associated with your profiles.

Lookback

90 days

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

{
    "export_type": "EVENTS",
    "from": "2024-01-01T00:00:00Z",
    "to": "now",
    "events": [
        "email_sent",
        "email_delivered",
        "email_open",
        "email_click",
        "email_unsubscribed",
        "email_bounced",
        "email_spam_complaint",
        "sms_sent",
        "sms_delivered",
        "sms_unsubscribed",
        "sms_bounced",
        "push_sent",
        "push_open",
        "push_bounced"
    ],
    "identifiers": [
        "custom_id"
    ]
}

Export file structure

This export will contain a list of events with it fields and an identifiers object.

Event fields

Identifiers object

Represents the identifiers of the profile concerned by the event.

Field

Description

Type

Required

profile_id

Unique identifier of the profile E.g.{"profile_id":"profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v"}

string

custom_id

Custom identifier of the profile E.g.{"custom_id":"User1"}

string

Event type

Exhaustive list of type for the event.

email_bounced: Triggered when an email fails to deliver.
email_click: Triggered when the recipient clicks a link in the email.
email_delivered: Triggered when the email is successfully accepted by the recipient's email server.
email_open: Triggered when the recipient opens the email.
email_sent: Triggered when the email is sent.
email_spam_complaint: Triggered when the recipient marks the email as spam.
email_unsubscribed: Triggered when the recipient unsubscribes from emails.
sms_sent: Triggered when an SMS is sent.
sms_bounced: Triggered when an SMS fails to deliver.
sms_delivered: Triggered when the SMS is successfully delivered.
sms_unsubscribed: Triggered when the recipient unsubscribes from SMS.
push_sent: Triggered when a push notification is sent.
push_bounced: Triggered when the push fails (e.g., invalid token).
push_open: Triggered when the user opens the app via the push notification.

Export file sample

This is a sample of the content of the export file you will receive.

Example

[
  {
      "ab_testing_status": null,
      "ab_testing_variant": null,
      "api_key": "6B29A8F1E7CD4B93AC1D0F52C4A19BE7",
      "event_date": "2025-08-29T13:05:55Z",
      "event_type": "push_sent",
      "identifiers": {
        "custom_id": "User1",
        "profile_id": "profile_1m9yqztq4w5gxs2pbkqkn8rt1agv0p9n"
      },
      "is_push_opt_in": true,
      "message_language": "default",
      "orchestration_id": "orchestration_0fuy7ah8kqtmvd3jcp2x96ge5n1rwxbq",
      "orchestration_name": "Batch welcome orchestration",
      "platform": "IOS",
      "sent_id": "9f3c1024-b238-11f0-89ea-5e9dcf083d3f",
      "step_id": "MESSAGE__t9HwKzL",
      "step_name": "Welcome push"
    },
    {
    "ab_testing_status": null,
    "ab_testing_variant": null,
    "event_date": "2025-09-02T15:10:24Z",
    "event_type": "sms_sent",
    "identifiers": {
      "custom_id": "User2",
      "profile_id": "profile_3r1vczm73kzq8ebfyt72cp4nm9qd2jk6"
    },
    "message_language": "default",
    "orchestration_id": "orchestration_0fuy7ah8kqtmvd3jcp2x96ge5n1rwxbq",
    "orchestration_name": "Batch welcome orchestration",
    "phone_country": "fr",
    "phone_number": "+33182837140",
    "sent_id": "sms_1b5uvrk84g3xmk2ze7w9tdapf6q1js0y",
    "sms_parts": 1,
    "step_id": "MESSAGE__pX7dQKz",
    "step_name": "Welcome sms"
  },
  {
    "ab_testing_status": null,
    "ab_testing_variant": null,
    "email_address": "jane.doe@demobatch.com",
    "event_date": "2025-09-03T13:34:51Z",
    "event_type": "email_sent",
    "identifiers": {
      "custom_id": "",
      "profile_id": "profile_0vnyhjdkt9bs0fx1znp5a4ew8mcz21td"
    },
    "mailbox_provider": "Gsuite",
    "message_language": "default",
    "orchestration_id": "orchestration_1q3cymdz0npk8g4xv67whjkb25r9emtc",
    "orchestration_name": "Email Marketing Campaign",
    "sent_id": "email_1vyqn54j0exu38wdg2tsmk7rz9ba4kyh",
    "step_id": "MESSAGE__Aq9KdLm",
    "step_name": null
  }
]

Profile Reachability Events

Use this to export the reachability events of your profiles.

Lookback

Reachability events are available since October 10, 2024. No events are available prior to this date. Lookback period will be 90 days.

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

{
  "export_type": "REACHABILITY",
  "from": "2024-01-01T00:00:00Z",
  "to": "now",
  "channels": [
    "push",
    "email",
    "sms"
  ],
  "identifiers": [
    "custom_id",
    "installation_id"
  ]
}

Export file structure

The export will contain a list of reachability events. Each event is composed of an event object and an identifiers object.

Field

Description

Type

Required

event

Representation of a reachability event object

object

identifiers

Representation of an identifiers object

object

Event Object

Representation of an reachability event object. It also describes a part of the profile state at the time of the event.

Identifiers object

Represents the identifiers of the profile concerned by the event.

Field

Description

Type

Required

profile_id

Unique identifier of the profile. E.g.{"profile_id":"profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v"}

string

custom_id

Custom identifier of the profile E.g.{"custom_id":"User1"}

string

installation_id

Installation identifier of the profile. Only available on PUSH channels E.g.{"installation_id":"828A7D76-3D5E-49DC-A863-2465070184C9"}

string

Event reasons

Exhaustive list of reasons for the event.

SUBSCRIBED_TO_SMS_MARKETING: The profile subscribed to SMS marketing.
UNSUBSCRIBED_FROM_SMS_MARKETING: The profile unsubscribed from SMS marketing.
PHONE_NUMBER_ADDED: The profile added a phone number.
PHONE_NUMBER_REMOVED: The profile removed a phone number.
PHONE_NUMBER_UPDATED: The profile updated a phone number.
SUBSCRIBED_TO_EMAIL_MARKETING: The profile subscribed to email marketing.
UNSUBSCRIBED_FROM_EMAIL_MARKETING: The profile unsubscribed from email marketing.
EMAIL_ADDRESS_ADDED: The profile added an email address.
EMAIL_ADDRESS_REMOVED: The profile removed an email address.
EMAIL_ADDRESS_UPDATED: The profile updated an email address.
SUBSCRIBED_TO_PUSH: The profile got an optin install.
UNSUBSCRIBED_FROM_PUSH: The profile unsubscribed from push notifications.
PUSH_TOKEN_ADDED: The profile added a push token.

Export file sample

This is a sample of the content of the export file you will receive.

Example

[
  {
    "event": {
      "channel": "SMS",
      "id": "6156b060574cb223e8c4ed47c5df1855",
      "timestamp": "2024-01-01T00:00:00Z",
      "reasons": [
        "PHONE_NUMBER_ADDED",
        "SUBSCRIBED_TO_SMS_MARKETING"
      ],
      "has_phone_number": true,
      "sms_marketing": "subscribed"
    },
    "identifiers": {
      "profile_id": "profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v",
      "custom_id": "User1",
      "installation_id": "5420388A-D2EF-4397-AC9A-999231DA50D5"
    }
  },
  {
    "event": {
      "channel": "EMAIL",
      "id": "6156b060574cb223e8c4ed47c5df1855",
      "timestamp": "2024-01-01T00:00:00Z",
      "reasons": [
        "SUBSCRIBED_TO_EMAIL_MARKETING"
      ],
      "has_email_address": true,
      "email_marketing": "subscribed"
    },
    "identifiers": {
      "profile_id": "profile_f8e9w2vnfdpg1pcqwp0cjkpjd3a3pfgt",
      "custom_id": "User2",
      "installation_id": "643B366B-A643-415B-9E60-3E525A11EF88"
    }
  },
  {
    "event": {
      "channel": "PUSH",
      "id": "6156b060574cb223e8c4ed47c5df1856",
      "timestamp": "2024-01-01T00:00:00Z",
      "reasons": [
        "SUBSCRIBED_TO_PUSH"
      ],
      "is_optin": true,
      "platform": "iOS"
    },
    "identifiers": {
      "profile_id": "profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v",
      "installation_id": "828A7D76-3D5E-49DC-A863-2465070184C9"
    }
  }
]

Responses

Success

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and an export ID. This ID can be used to get status information about your export request using the Project Export API endpoints.

{
    "id": "export_nvctr8tgdjf7bppacxxt2aeemnjehfmw"
}

Failure

If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at support@batch.com if you need further support.

See the list of potential failures in the API Description.

PreviousMass update profile NextAudiences

Last updated 1 day ago