Export profile data

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

The Profile 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

application/json

objectoptional

application/json

application/json

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /2.4/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: 144

{
  "export_type": "ATTRIBUTES",
  "attributes": [
    "$email_address",
    "$language",
    "firstname",
    "is_premium"
  ],
  "identifiers": [
    "custom_id",
    "installation_ids"
  ]
}

export_attributesexport_eventsexport_reachability

{
  "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:

https://api.batch.com/2.4/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": [
        "$email_address",
        "$email_marketing",
        "$phone_number",
        "$sms_marketing",
        "$region",
        "$timezone",
        "$language",
        "first_name",
        "is_premium"
    ],
    "identifiers": [
        "custom_id",
        "installation_ids"
    ]
}

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

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",
        "sms_sent",
        "push_sent"
    ],
    "identifiers": [
        "custom_id"
    ]
}

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.

Field	Description	Type	Required
export_type	Channel where the event happened E.g.{"channel":["SMS","EMAIL","PUSH"]}	string
id	Unique identifier of the event E.g.{"id":"6156b060574cb223e8c4ed47c5df1855"}	string
timestamp	UTC date in a RFC 3339 format E.g.{"timestamp":"2024-01-01T00:00:00Z"}	string
reasons	Reasons why an event has been triggered. See "Event Reasons" E.g.{"reasons":["SUBSCRIBED_TO_SMS_MARKETING","PHONE_NUMBER_ADDED"]}	array
has_phone_number	Only for SMS channel, means the profile has a phone number E.g.{"has_phone_number":true}	boolean
has_email_address	Profile's marketing email subscription E.g.{"has_email_address":true}	boolean
sms_marketing	Profile's marketing SMS subscription E.g.{"sms_marketing":"subscribed"}	string
email_marketing	Profile's marketing emails subscription E.g.{"email_marketing":"subscribed"}	string
is_optin	Installation's notification system opt-in state E.g.{"is_optin":false}	boolean
platform	Platform of the installation (iOS/Android/Webpush). Only available on PUSH channels E.g.{"platform":"iOS"}	string

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"
    }
  },
  {
    "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_063kxgw384nn7k3wxgsa0xfbd0pgmd9v",
      "custom_id": "User1"
    }
  },
  {
    "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",
      "custom_id": "User1",
      "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 [email protected] if you need further support.

See the list of potential failures in the API Description.