Introduction
This site provides documentation, examples and guides for the public API of the APSIS One platform.
Getting started
Start by reading about reaching our public API from your region. To be able to call our API you also need to authenticate. Finally familiarize yourself with the important concepts regarding the limits.
Managing your APSIS One data
Once you know how to call the API you can start building your integration. The sidebar provides documentation to all the currently supported endpoints under the API reference section.
The endpoints inside the Definitions and Folders categories let you interact with your account configuration.
Different aspects of individual profile management are supported by the APIs inside the Profiles, Attributes, tags and events, Segments and Consents categories. The Profile import and Profile export categories provide means of bulk profile management.
Finally, the endpoints to manage your activities are placed inside the Email, SMS, Forms & Pages, Website and Marketing Automation categories.
Guides
This site also provides the guides for common use cases. You can find them in the Guides section on the sidebar.
Knowledge base
See our knowledge base for more information about the APSIS One API including more detailed getting started tutorials, pricing and many guides related to profile management.
What's new
Our CHANGELOG provides information about the new API features as well as the updates to the existing API functionality.
We often preview the upcoming endpoints in the In development section of this site. This gives you some insight into the future of APSIS One API. Note that these features are likely to change while we're working on them.
Have questions?Contact customerservice.apsis@efficy.com to learn more
Host names
APSIS One uses different URLs in Europe and Asia regions. The same applies to APSIS One API.
Note that the code samples on this page refer to the Europe region.
Europe
Customers from Europe who access APSIS One via https://app.apsis.one/ use https://api.apsis.one/ base URL when building integrations.
Full list of host names used by APSIS One API in Europe:
api.apsis.onefor majority of endpointss3.eu-west-1.amazonaws.comandfile-import-uploads-875773028321-prod.s3.eu-west-1.amazonaws.comfor file importexports.api.apsis.oneandemail-report.api.apsis.onefor file export
Asia
Customers from Asia who access APSIS One via https://apac.apsis.one/ use https://api-apac.apsis.one/ base URL when building integrations.
Full list of host names used by APSIS One API in Asia:
api-apac.apsis.onefor majority of endpointss3.ap-southeast-1.amazonaws.comandfile-import-uploads-530585884979-prod-apac.s3.ap-southeast-1.amazonaws.comfor file importexports.api-apac.apsis.oneandemail-report.api-apac.apsis.onefor file export
IP addresses
APSIS One API currently uses dynamic public IP addresses.
If you require allowlisting the IP addresses your infrastructure can connect to, refer to the AWS IP address ranges guide.
✉️ Have questions?Contact customerservice.apsis@efficy.com to learn more
Introduction
APSIS One API uses Bearer Authentication as designed in RFC 6750. This guide will teach you how to authenticate your integration with our API.
Create an API key
Create an API key in your APSIS One account settings. You can have multiple API keys to better manage your integrations with APSIS One API. Once you've deleted an API key in APSIS One account settings, APSIS One API will no longer accept it.
Add the API key to your integration settings
Store client ID and secret key in your integration settings. These are in fact the credentials to APSIS One API and thus it's sensitive data so it's best to encrypt them at rest and in transfer.
Obtain an access token
Call our token endpoint providing your client ID and secret key in the request body:
curl --location --request POST 'https://api.apsis.one/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "client_credentials",
"client_id": "b49b39a0-82a1-11ec-8017-5d554e8551d6",
"client_secret": "4n0TpfkaedYOkIljy0mtAs4Y2r2qR5XGrBhpt20Cf3LYaE45piAPunlVAq4jbJBV"
}'
The response will contain your access token along with the scheme and expiration period:
{
"access_token": "eyJhbGciOiJSUz...",
"expires_in": 86400,
"token_type": "Bearer"
}
Cache the access token
Store the access_token value in your integration cache and reuse it during the time when it remains valid to avoid redundant calls to the token endpoint.
Currently our access tokens are valid for up to 24 hours. In your client, decode the access_token and retrieve the expiration time from the exp claim. When the token is close to expiry, request it again using the token endpoint.
The deprecated expires_in response property is provided for backwards compatibility. The use of this property is discouraged.
To encourage proper authentication token caching, the token endpoint is rate limited more strictly. When this limit is reached, HTTP 429 Too Many Requests is returned. When this happens, retry the call with exponential back-off.
Making calls to APSIS One API
When making calls to other endpoints of this API, provide the cached authentication token as Authorization: Bearer <access token> header. Here's an example:
curl --location --request GET 'https://api.apsis.one/audience/keyspaces' \
--header 'Authorization: Bearer eyJhbGciOiJSUz...'
Video guide
Here's a video guide that covers all of the above topics:
✉️ Have questions?Contact customerservice.apsis@efficy.com to learn more
Introduction
This page provides the information about the current limits implemented in APSIS One API.
Read more about standard service limits in this article.
⚠️ Limits can changeFor the benefit of our customers, we are constantly improving the APSIS One platform stability and performance. Public API limits are one of the tools allowing us to achieve this goal. For that reason, we reserve the right to change the limits listed on this page without notice.
Rate limits
Rate limits are applied on the account level, independent of how many API keys you use.
- Most endpoints allow for up to 100 requests per second
- Authentication token request - up to 10 requests per minute
- Profile imports - up to 10 requests per minute
- Profile exports - up to 1 request per second
- Event exports - up to 1 request per minute
- Export downloads - up to 60 requests per minute
When you reach these limits, HTTP 429 Too Many Requests is returned.
Profile key based rate limits
Many features in APSIS One API allow single profile management. Some examples are Set attributes on a profile and Add events to a profile.
To protect the platform stability, increase the performance and encourage the proper use by combining multiple updates into a single request or choosing bulk features, like Request profile import (version 2), the following rate limits are put in place:
- Consecutive operations using the same profile key - up to 10 requests per second
Hints for mitigating these rate limits:
- Combine multiple profile attribute values into a single call when updating profiles using Set attributes on a profile
- Combine multiple profile events into a single call when using Add events to a profile
Size limits
Request body size is limited to 100 kB. Exceptions:
All lists accepted in the APSIS One API request bodies are limited based on the specific platform feature.
When you reach these limits, HTTP 413 Request Entity Too Large is returned.
Import limits
Imports have limits specific to the import files and frequency. Find details in the endpoint specification:
Export limits
Exports are limited in terms of the time frame as well as the data to include in the export file. Endpoint specification provides details:
✉️ Have questions?Contact customerservice.apsis@efficy.com to learn more
Get keyspaces
Keyspaces
Keyspaces allow to identify the profiles using different profile keys. Specific operations can be performed on a profile identified through a particular keyspace.
Unique identifiers
Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace.
Profile access
Profile access via One API is allowed through the specified keyspaces only.
Keyspace permissions
Specific profile attribute and tag types can be read or written when a profile is identified through a profile key in a specific keyspace. To find out which, use the include_keyspace_permissions request parameter with Get attributes and Get all tags.
Subscription management
Subscriptions (consent) can only be managed via keyspaces with manage_subscriptions flag set to true.
Keyspaces supported by APSIS One API
Full support:
- Email Keyspace (
com.apsis1.keyspaces.email) uses email address as key and can be used to perform all profile operations. - SMS Keyspace (
com.apsis1.keyspaces.mobile) uses mobile phone number as key and can be used to perform all profile operations. - CRM Keyspace (
com.apsis1.keyspaces.crm-id) uses CRM-ID as key and can be used to perform all profile operations. Profile keys in this keyspace are initialized in a third party system.
Partial support:
- Export Keyspace (
com.apsis1.keyspaces.export) uses export keys to identify the profiles. These profile keys appear in the export files provided by this API and in the browser address bar when looking at a profile. This keyspace is read only and allows for reading profile attributes, tags, events and consents. It also supports locking, deleting and merging profiles.
Authorizations:
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/keyspaces \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.keyspaces.email",
- "name": "Email Keyspace",
- "description": "Email Keyspace",
- "manage_subscriptions": true
}
]
}Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/channels \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.channels.web",
- "name": "Web",
- "description": "Web Channel"
}
]
}Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/sections \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "name": "Default",
- "description": "My default section",
- "id": "1234"
}
]
}Get attributes
Gets all attributes within a specific section that are not hidden. Includes default and custom attributes.
When any e-commerce integration is connected to the specified section then also e-commerce attributes are returned.
In its requests and responses, APSIS One API accepts and returns version IDs and dates as strings. On the other hand, attribute value data types follow attribute types as described in this Help Center article.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_keyspace_permissions | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/attributes?include_keyspace_permissions=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.attributes.firstname",
- "name": "First name",
- "description": "First name",
- "versions": [
- {
- "id": "1234",
- "type": [
- "string"
], - "deprecated_at": "2017-07-21T17:32:28.761Z",
- "valid_from": "2017-07-21T17:32:28.761Z"
}
], - "keyspace_permissions": {
- "com.apsis1.keyspaces.email": [
- "read",
- "write"
], - "com.apsis1.keyspaces.sms": [
- "read"
]
}
}
]
}Get topics (version 2)
About consent
If a profile wants to receive communication regarding a specific topic over a specific channel (email or SMS), they must first give consent. The consent information is saved in APSIS One on a profile level along with the topic and the channel the consent is given for.
The following consent types are supported by APSIS One:
opt-in- profile permits communicationopt-out- profile forbids any communicationpending-opt-in- communication permission waits for the profile to confirm it (not supported by APSIS One API yet)confirmed-opt-in- profile permits communication which they also confirmed (not supported by APSIS One API yet)
Confirming the consent, also known as double opt-in, is usually done via a link in an email that is sent to the profile.
Get topics
Gets all topics from a specified section
More information
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/v2/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/topics \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "id": "12423",
- "name": "Shoes",
- "description": "New shoe offers",
- "folder_discriminator": "com.apsis1.folders.topic.promotions-pg5fiix3up"
}
]
}Get all tags
Get all tags defined within a specific section. Only tags that are not hidden are returned.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_keyspace_permissions | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/tags?include_keyspace_permissions=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "items": [
- {
- "discriminator": "usercreated.attributes.vip-npqjeo3mbb",
- "name": "VIP",
- "id": "1234",
- "keyspace_permissions": {
- "com.apsis1.keyspaces.email": [
- "read",
- "write"
], - "com.apsis1.keyspaces.sms": [
- "read"
]
}
}
]
}Create a single tag
Create a single tag
Creates a new tag with a provided name within a specific section
Limits
A maximum of 200 tags is allowed per section. The HTTP 400 Bad Request response status code is returned if a tag is attempted to be added over this limit.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
| name required | string [ 1 .. 255 ] characters Tag name |
Responses
Request samples
- Payload
- Curl
{- "name": "VIP"
}Response samples
- 201
- 400
- 404
- default
{- "discriminator": "usercreated.attributes.vip-npqjeo3mbb",
- "name": "VIP",
- "id": "1234"
}Get a single tag
Get a single tag within a specific section
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| tag_discriminator required | string Tag discriminator |
query Parameters
| include_keyspace_permissions | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/tags/%7Btag_discriminator%7D?include_keyspace_permissions=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "discriminator": "usercreated.attributes.vip-npqjeo3mbb",
- "name": "VIP",
- "id": "1234",
- "keyspace_permissions": {
- "com.apsis1.keyspaces.email": [
- "read",
- "write"
], - "com.apsis1.keyspaces.sms": [
- "read"
]
}
}Update a single tag
Updates a name of a single tag
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| tag_discriminator required | string Tag discriminator |
Request Body schema: application/jsonrequired
| name required | string [ 1 .. 255 ] characters Tag name |
Responses
Request samples
- Payload
- Curl
{- "name": "VIP"
}Response samples
- 200
- 400
- 404
- default
{- "discriminator": "usercreated.attributes.vip-npqjeo3mbb",
- "name": "VIP",
- "id": "1234"
}Get events
Get all events defined within a specific section that are not hidden.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_keyspace_permissions | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/events?include_keyspace_permissions=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.events.website.auto-collect.page-view",
- "name": "Auto Collect - Page view",
- "description": "Events collected on page view",
- "versions": [
- {
- "id": "1234",
- "type": {
- "activityId": "f567a6ee-a109-4b06-a4c5-264ee5e68ac7",
- "transactionId": "acf61b64-a449-4849-9770-0f1ae0ff9bcd",
- "toEmail": "john.doe@example.com",
- "toName": "John Doe"
}, - "deprecated_at": "2017-07-21T17:32:28.761Z",
- "valid_from": "2017-07-21T17:32:28.761Z"
}
], - "keyspace_permissions": {
- "com.apsis1.keyspaces.email": [
- "read",
- "write"
], - "com.apsis1.keyspaces.sms": [
- "read"
]
}
}
]
}Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/segments \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1",
- "name": "Segment1",
- "description": "Segment 1 description",
- "versions": [
- {
- "id": "14552",
- "query": "(section(1898).attribute(11737)) && (section(1898).attribute(11738)) && (section(1898).attribute(11739))\""
}
]
}
]
}Get segment
Get a single segment.
Authorizations:
path Parameters
| segment_discriminator required | string Example: usercreated.segments.europe-d8jye63u2y Segment discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/segments/usercreated.segments.europe-d8jye63u2y \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1",
- "name": "Segment1",
- "description": "Segment 1 description",
- "versions": [
- {
- "id": "14552",
- "query": "(section(1898).attribute(11737)) && (section(1898).attribute(11738)) && (section(1898).attribute(11739))\""
}
]
}Get segment version
Get specific segment version.
Authorizations:
path Parameters
| segment_discriminator required | string Example: usercreated.segments.europe-d8jye63u2y Segment discriminator |
| version_id required | string Resource version ID |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/segments/usercreated.segments.europe-d8jye63u2y/versions/%7Bversion_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "14552",
- "query": "(section(1898).attribute(11737)) && (section(1898).attribute(11738)) && (section(1898).attribute(11739))\""
}Get all topic folders
Gets the full folder tree for topics in a specific section. Use with Get topics (version 2) to match your topics with what you see in APSIS One under Audience > Subscriptions.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/folders/topic/sections/com.apsis1.sections.user-created.default-qfbh7w8775/folders \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "discriminator": "com.apsis1.folders.topic.root-nlrl3fhezd",
- "subfolders": [
- {
- "discriminator": "com.apsis1.folders.topic.promotions-pg5fiix3up",
- "name": "Promotions"
}, - {
- "discriminator": "usercreated.targets.springsales-h2d383dnt8",
- "name": "Spring sales"
}
]
}Create a new profile
Unique identifiers
Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace.
Create a new profile
This feature creates a new profile in your account. This profile is identified by the keyspace_discriminator and profile_key you provide in the request. In the section designated by section_discriminator, the value is set for the attribute mapped to the keyspace. This value is the same as the profile key.
This feature allows creating profiles in custom keyspaces (unique identifiers).
The keyspace and section must exist prior to calling this endpoint.
As an example, let's say you want to create a profile in the Email keyspace and the context of your Europe section. Your call would look like this:
POST /audience/keyspaces/com.apsis1.keyspaces.email/sections/usercreated.sections.europe-r6tz73a27t/profiles
{
"profile_key": "com.apsis1.keyspaces.email"
}
Profiles and attributes
Profiles are created on account level whereas attributes and tags are defined on sections. They are then set on profiles on section level as well.
Even though default attributes like First Name or Email have the same names across sections, setting their value on a profile in one section will not affect their values in other sections. Custom attributes and tags created in one section can only set on profiles on that section level.
Mapped attribute values
Each keyspace in the account has a mapped attribute in all sections. For example, the email keyspace, com.apsis1.keyspaces.email, has the Email attribute, com.apsis1.attributes.email, mapped to it in each section.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
| profile_key required | string Uniquely identifies a profile through a specified keyspace |
Responses
Request samples
- Payload
- Curl
{- "profile_key": "c9251fad-5661-4200-a054-8033963f4c53"
}Response samples
- 201
- 400
- 403
- 404
- 410
- default
{- "keyspace_discriminator": "string",
- "profile_key": "string"
}Lock a profile
Profile will be locked and its data permanently deleted. Profile lock is permanent and irreversible.
APSIS One will generate an encrypted, anonymous ID for the profile and block any future attempts of adding a profile matching this ID. It is not possible to import or create a locked profile nor for them to opt-in again. This applies to all keyspaces.
Unless strictly necessary, abstain from locking Profiles.
Locking Profiles cannot be undone and will prevent individuals from opting in into your communications in the future with the same email address or mobile number.
It is recommended to remove profiles using DELETE /audience/keyspaces/{keyspace_discriminator}/profiles/{profile_key} endpoint instead.
Read more about locking profiles in this Help Center article.
Profiles are on account level
Profiles are created on account level and NOT on section level. Using this endpoint locks the entire profile account-wide, not just its part that belongs to a specific section.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Responses
Request samples
- Curl
curl --request PUT \ --url https://api.apsis.one/audience/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com/locks \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 400
- 403
- 404
- default
{- "status": 400,
- "title": "Bad Request"
}Switch profile unique identifier
Unique identifiers
Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace.
Switch profile unique identifier
This feature removes one of the current profile keys from an existing profile and replaces it with another, new profile key within a different keyspace.
If you only need to change a profile key value within the same keyspace, Set attributes on a profile (version 2) feature is recommended over this one.
How it works
The request path parameters, keyspace, profile key and section, are used to locate the profile that will be changed.
Once the profile is located, the request body specifies two unique identifiers:
from- This unique identifier will be removed from the profile, unless a mapped attribute value exists in another section on that profile (more on that below). This profile key must exist on the profile located via the request path parameters. The unique identifier used to locate the profile can also be targeted with thefromrequest body property.to- This new unique identifier will be created on the profile. Such profile key must not yet exist on the selected profile or any other profile in the account. Also any existing mapped attribute value must correspond to the new profile key value.
After calling this endpoint you are able to locate the profile using the new unique identifier.
Unique identifier removal warning
In most scenarios, this feature removes the the profile key specified in the from request body property from the profile. You will no longer be able to locate the profile using that profile key.
Mapped attribute values
Each keyspace in the account has a mapped attribute in all sections. For example, the email keyspace, com.apsis1.keyspaces.email, has the Email attribute, com.apsis1.attributes.email, mapped to it in each section.
Let's say you're switching to a unique identifier in com.apsis1.keyspaces.email keyspace. This works only if you provide a profile_key value that is the same as the email attribute value for the selected profile.
Now, imagine you're switching from a unique identifier in com.apsis1.keyspaces.crm-id keyspace in the context of a specific section. On top of that, in another section that same profile has a value set on an attribute that is mapped to com.apsis1.keyspaces.crm-id keyspace, the CRM-ID attribute. If that's the case, the original, from profile key is not removed from the profile. The new, to profile key is still created.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
required | object (UniqueIdentifier) Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace. |
required | object (UniqueIdentifier) Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace. |
Responses
Request samples
- Payload
- Curl
{- "from": {
- "keyspace_discriminator": "com.apsis1.keyspaces.mobile",
- "profile_key": "4812926715"
}, - "to": {
- "keyspace_discriminator": "com.apsis1.keyspaces.crm-id",
- "profile_key": "c9251fad-5661-4200-a054-8033963f4c53"
}
}Response samples
- 400
- 403
- 404
- 409
- 410
- default
{- "status": 400,
- "title": "Bad Request"
}Delete a profile
Profile will be permanently deleted along with its consents and events. This operation is permanent and irreversible.
Read more about deleting profiles in this Help Center article.
Profiles are on account level
Profiles are created on account level and NOT on section level. Using this endpoint deletes the entire profile account-wide, not just its part that belongs to a specific section.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Responses
Request samples
- Curl
curl --request DELETE \ --url https://api.apsis.one/audience/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 400
- 403
- 404
- default
{- "status": 400,
- "title": "Bad Request"
}Merge two profiles
Merges two profiles designated in the body using keyspace discriminator and profile key. As a result of the merge, both profile keys in both keyspaces will point to the same physical profile. Merging profiles using profile keys from different keyspaces is supported. Merge is both associative and commutative so you can do (A+B)+C if you need to merge more than two profiles.
If any of the merged profiles does not exist then it is created along the way. Also, if one of the merged profiles is locked then the other profile will be locked as well if the merge succeeds.
The use of Export Keyspace (com.apsis1.keyspaces.export) for both profiles yields the best results.
Caution! This API does not verify the physical owners of the profiles to be merged. The caller is obliged to make sure both profiles belong to the same physical individual prior to merging them with this endpoint.
Error scenarios
The following error scenarios are specific to this feature:
400 Bad RequestExactly two profiles were not provided in the request body or
profile_keyis not valid404 Not FoundOne of the specified keyspaces or profiles were not found
409 ConflictAttempt to merge two profiles where any of Email, Mobile and/or CRM ID attributes have conflicting values. Update the conflicting attribute value(s) on one of the profiles and retry the merge.
One of the profiles has reached its merge limit of 500 merges per profile
Read more about profile merge in this Help Center article
Authorizations:
Request Body schema: application/jsonrequired
required | Array of objects (ProfileToMerge) = 2 items |
Responses
Request samples
- Payload
- Curl
{- "profiles": [
- {
- "keyspace_discriminator": "com.apsis1.keyspaces.email",
- "profile_key": "john.doe@example.com"
}, - {
- "keyspace_discriminator": "com.apsis1.keyspaces.mobile",
- "profile_key": "46287917256"
}
]
}Response samples
- 400
- 403
- 404
- 409
- default
{- "status": 400,
- "title": "Bad Request"
}Unmerge a profile
Unmerge a profile
Unmerge a single profile designated by the keyspace discriminator and the profile key provided in the request from a group of two or more merged profiles
For example let's assume there are merged profiles A+B+C with keyspaces email + mobile + CRM (respectively). When we request to unmerge profile B via mobile keyspace then profile B is unmerged from A+B+C giving a standalone profile B and merged profile A+C. Data from profile B which was part of A+B+C before the unmerge call remains under A+C profile after profile B has been unmerged.
A previously unmerged profile can be merged back to the same or a new group.
If a profile is stand-alone then a request to unmerge it does not result in an error.
Error scenarios
The following error scenarios are specific to this feature:
400 Bad RequestAn attempt was made to unmerge a canonical profile
404 Not FoundThe specified keyspace or profile was not found
410 GoneThe profile that is requested to be unmerged is locked
Read more about profile merge in this Help Center article
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Responses
Request samples
- Curl
curl --request DELETE \ --url https://api.apsis.one/audience/profiles/merges/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 400
- 403
- 404
- 410
- default
{- "status": 400,
- "title": "Bad Request"
}Evaluate a profile
Evaluates a single profile against a given list of segments and returns matches, i.e. a list of segments to which this profile belongs
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Request Body schema: application/jsonrequired
required | Array of objects non-empty |
| time_zone required | string In segment definition, dates are stored without time zones. Time zone is used to resolve the dates when evaluating a segment, i.e. calculating the profiles to be included in a specific segment. |
Responses
Request samples
- Payload
- Curl
{- "segments": [
- {
- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1"
}, - {
- "discriminator": "com.apsis1.segments.ggs2rfd-Segment2",
- "version_id": "1234"
}
], - "time_zone": "Europe/Stockholm"
}Response samples
- 200
- 400
- 403
- 410
- default
{- "matches": {
- "segments": {
- "com.apsis1.segments.asdfsf2312rfd-Segment1": true,
- "com.apsis1.segments.ggs2rfd-Segment2|1234": false
}
}
}Get segment trend
Get the number of profiles matching the provided provided segment over time. This lets you build a trend graph similar to the one seen in Audience - Segments in APSIS One.
For each sampling point provided in the request, the count of known and unknown profiles is returned.
Sampling points should be provided as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| segment_discriminator required | string Example: usercreated.segments.europe-d8jye63u2y Segment discriminator |
Request Body schema: application/jsonrequired
| sampling_points required | Array of strings <date-time> (DateTime) [ 1 .. 25 ] items [ items <date-time > ] List of instants for which the counts of profiles matching the segment should be returned |
| timezone required | string In segment definition, dates are stored without time zones. Time zone is used to resolve the dates when evaluating a segment, i.e. calculating the profiles to be included in a specific segment. |
Responses
Request samples
- Payload
- Curl
{- "sampling_points": [
- "2021-08-25T12:00:00.000Z",
- "2021-08-26T12:00:00.000Z",
- "2021-08-27T12:00:00.000Z"
], - "timezone": "Europe/Stockholm"
}Response samples
- 200
- 400
- 413
- 429
- default
{- "matching_profile_count": {
- "2021-08-25T12:00:00.000Z": {
- "known": 0,
- "unknown": 0
}, - "2021-08-26T12:00:00.000Z": {
- "known": 352,
- "unknown": 21
}, - "2021-08-27T12:00:00.000Z": {
- "known": 451,
- "unknown": 52
}
}
}Create a consent (version 2)
About consent
If a profile wants to receive communication regarding a specific topic over a specific channel (email or SMS), they must first give consent. The consent information is saved in APSIS One on a profile level along with the topic and the channel the consent is given for.
The following consent types are supported by APSIS One:
opt-in- profile permits communicationopt-out- profile forbids any communicationpending-opt-in- communication permission waits for the profile to confirm it (not supported by APSIS One API yet)confirmed-opt-in- profile permits communication which they also confirmed (not supported by APSIS One API yet)
Confirming the consent, also known as double opt-in, is usually done via a link in an email that is sent to the profile.
Create a consent
Create a profile consent of a specific type regarding a given topic over a selected channel. Provide a reason for consent. Optionally, specify the source of consent which we'll default to One API if not provided.
Profile is identified by keyspace discriminator and profile key. Topic is identified by section discriminator and topic discriminator.
HTTP response status codes specific to this endpoint:
201 Created- a consent to the requested topic did not previously exist on the requested profile and was now created204 No Content- an existing consent to the requested topic was updated409 Conflict- transition from the existing to a desired consent type is not supported (mostly happens when you attempt to update consent type to the same value that is already set on a profile)
More information
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
| topic_discriminator required | string |
| channel_discriminator required | string |
| type required | string Enum: "opt-in" "opt-out" "pending-opt-in" "confirmed-opt-in" Consent type |
| reason required | string [ 3 .. 256 ] characters Reason for giving the consent |
| source | string [ 3 .. 256 ] characters Source of the consent information. Defaults to |
Responses
Request samples
- Payload
- Curl
{- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "channel_discriminator": "com.apsis1.channels.email",
- "type": "opt-in",
- "reason": "Subscribed via summer sale form",
- "source": "Summer sale subscription form"
}Response samples
- 400
- 403
- 404
- 409
- 410
- default
{- "status": 400,
- "title": "Bad Request"
}Get consents (version 2)
About consent
If a profile wants to receive communication regarding a specific topic over a specific channel (email or SMS), they must first give consent. The consent information is saved in APSIS One on a profile level along with the topic and the channel the consent is given for.
The following consent types are supported by APSIS One:
opt-in- profile permits communicationopt-out- profile forbids any communicationpending-opt-in- communication permission waits for the profile to confirm it (not supported by APSIS One API yet)confirmed-opt-in- profile permits communication which they also confirmed (not supported by APSIS One API yet)
Confirming the consent, also known as double opt-in, is usually done via a link in an email that is sent to the profile.
Get consents
Get all or selected types of consents for different topics over various channels currently existing for a specific profile.
Profile is identified by keyspace discriminator and profile key. Topic is identified by section discriminator and topic discriminator.
Suppression
🚧 In development
This feature is currently in development and it's not meant to be used yet
Suppression is the APSIS One feature that allows users to block any communication to a specific address. It takes priority over any profile consents. Useful when one of your customers calls you and requests to halt all communication.
As a result, for a profile to receive any marketing communication from the APSIS One platform, two conditions must be met:
- an opt-in or confirmed opt-in consent for a specific topic over a specific channel must exist on the profile
- the address must not be suppressed
Note that consent is given on the profile level whereas suppression works on the address level.
This APSIS One API endpoint provides information about the existing suppression, if any. Existing suppression for the address that is used as profile_key is always returned. If you need to check if any suppression exists for another address, use suppression_channel_discriminator and suppression_address query string parameters.
In the example response, despite being subscribed to a topic over two channels, the profile will only receive email communication since the address on the SMS channel is suppressed.
More information
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| consent_types | Array of strings Items Enum: "opt-in" "opt-out" "pending-opt-in" "confirmed-opt-in" If provided in the request, this comma separated list of consent types will filter the consents in the response.
For example: |
| suppression_channel_discriminator | string Example: suppression_channel_discriminator=com.apsis1.channels.sms Allows checking if any suppression exists for a specific address. Used together with |
| suppression_address | string Example: suppression_address=41726480987 Allows checking if any suppression exists for a specific address. Used together with |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/v2/audience/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com/sections/com.apsis1.sections.user-created.default-qfbh7w8775/consents?consent_types=SOME_ARRAY_VALUE&suppression_channel_discriminator=com.apsis1.channels.sms&suppression_address=41726480987' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 400
- 404
- default
{- "items": [
- {
- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "channel_discriminator": "com.apsis1.channels.email",
- "type": "opt-in",
- "reason": "Subscribed via summer sale form",
- "source": "Summer sale subscription form",
- "modified_at": "2017-07-21T17:32:28.761Z"
}, - {
- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "channel_discriminator": "com.apsis1.channels.sms",
- "type": "opt-in",
- "reason": "Subscribed via summer sale form",
- "source": "Summer sale subscription form",
- "modified_at": "2017-07-21T17:32:28.761Z"
}
], - "suppression": [
- {
- "channel_discriminator": "com.apsis1.channels.sms",
- "address": "41726480987",
- "reason": "Customer complain"
}
]
}Request profile import Deprecated
Request a profile import into APSIS One.
Import is an asynchronous operation. Once it's been requested you'll receive a response that contains the file upload URL with embedded credentials and the expiration details.
Upload your import file using that URL. APSIS One API profile import supports CSV files (content type text/csv).
In its requests and responses, APSIS One API supports date and time formatted as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.
Import files support more date formats as described in this Help Center article. However these dates will be converted to a format corresponding to the type of the attribute the import file column is mapped to. Read more about attribute types in this Help Center article.
Once you've uploaded the file you can check the status using the corresponding GET /audience/sections/{section_discriminator}/imports/{import_id} endpoint.
The manage_subscriptions flag must be true on the keyspace used or HTTP 403 Forbidden response status code is returned.
All the attributes and tags you are trying to set during the import need to be allowed to WRITE through the selected keyspace. If any of them is not, HTTP 403 Forbidden response status code is returned.
Limits
The import file should be uploaded within 5 minutes from requesting the import. Best upload it immediately.
The maximum import file size is 50 MB. Split your import into multiple files and import requests to mitigate this.
Pending import count limit. If reached, HTTP 429 Too Many Requests is returned.
The import file considerations are the same when importing via APSIS One as when importing via this API. They've been described in this Knowledge Base article.
Understanding import failures
For every import, we're generating a report that contains statistics and detailed information about the import errors. See this Knowledge Base article.
Deprecated
Use version 2 instead.
Historically, this endpoint supports creating profile keys in multiple keyspace with one request by adding more than one object inside the keyspace_mappings request body parameter. We're moving away from this behavior in profile imports. When channel-specific topics are enabled on your account, this endpoint no longer supports creating multiple profile keys anymore. A request with multiple keyspace_mappings is rejected with the HTTP 400 Bad Request response status code. In rare cases when multiple profile keys are required, request multiple imports for your profiles.
Inside consent_mappings, for channel-specific topics the channel_discriminator parameter must correspond to the topic_discriminator parameter
Version 2 of the Profile Import feature does not use address_field_selector. Consents are created using the addresses mapped to the Email or Mobile attributes, depending on the consent channel.
More information
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
required | Array of objects [ 1 .. 10 ] items |
object | |
Array of objects <= 5 items | |
Array of objects <= 100 items | |
required | Array of objects [ 1 .. 100 ] items |
Responses
Request samples
- Payload
- Curl
{- "keyspace_mappings": [
- {
- "keyspace_discriminator": "com.apsis1.keyspaces.email",
- "field_selector": "email-address",
- "merge_profiles": false
}
], - "options": {
- "update_existing_profiles": true,
- "clear_existing_attributes": true
}, - "consent_mappings": [
- {
- "address_field_selector": "email-address",
- "consents": [
- {
- "resubscribe_if_opted_out": false,
- "field_selector": "mens-clothing-shoes",
- "channel_discriminator": "com.apsis1.channels.email",
- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "type": "opt-in"
}
]
}
], - "tag_mappings": [
- {
- "tag_discriminator": "usercreated.attributes.vip-npqjeo3mbb"
}
], - "attribute_mappings": [
- {
- "field_selector": "address",
- "attribute_version_id": "1234"
}
]
}Response samples
- 201
- 400
- 403
- 404
- 429
- default
{- "import_id": "234345345-c862-4a48-45455-7da1ac0e31ew",
- "file_upload_body": {
- "key": "string",
- "success_action_status": "string",
- "policy": "string",
- "content-type": "string",
- "x-amz-meta-id": "string",
- "x-amz-algorithm": "string",
- "x-amz-credential": "string",
- "x-amz-date": "string",
- "x-amz-signature": "string"
}, - "file_upload_url_expires_at": "string"
}Request profile import (version 2)
Request a profile import into APSIS One.
Import is an asynchronous operation. Once it's been requested you'll receive a response that contains the file upload URL with embedded credentials and the expiration details.
Upload your import file using that URL. APSIS One API profile import supports CSV files (content type text/csv).
In its requests and responses, APSIS One API supports date and time formatted as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.
Import files support more date formats as described in this Help Center article. However these dates will be converted to a format corresponding to the type of the attribute the import file column is mapped to. Read more about attribute types in this Help Center article.
Once you've uploaded the file you can check the status using the corresponding GET /audience/sections/{section_discriminator}/imports/{import_id} endpoint.
The manage_subscriptions flag must be true on the keyspace used or HTTP 403 Forbidden response status code is returned.
All the attributes and tags you are trying to set during the import need to be allowed to WRITE through the selected keyspace. If any of them is not, HTTP 403 Forbidden response status code is returned.
Limits
The import file should be uploaded within 5 minutes from requesting the import. Best upload it immediately.
The maximum import file size is 50 MB. Split your import into multiple files and import requests to mitigate this.
Pending import count limit. If reached, HTTP 429 Too Many Requests is returned.
The import file considerations are the same when importing via APSIS One as when importing via this API. They've been described in this Knowledge Base article.
Understanding import failures
For every import, we're generating a report that contains statistics and detailed information about the import errors. See this Knowledge Base article.
Version 2
Keyspaces and consents are now independent. You are able to create profiles (and profile keys) in a keyspace of your choice (e.g. CRM) and at the same time create consents for these profiles to the topics that are specific to channels not related to that keyspace (e.g. email or SMS).
Profiles (and profile keys) are created in a single keyspace. Profile merge is not supported.
This version of the Profile Import feature supports two kinds of topics, channel-specific and not, in the following manner:
- If you're creating a consent for a channel-specific topic then you can omit the
channel_discriminatorproperty in the request body. If you provide it then it must match the channel configured for the topic. - To create a consent for a topic that is not channel-specific you need to provide the
channel_discriminatorrequest body property as we need to know over which channel the consent should be created
Inside consent_mappings, the channel is inferred from the topic provided in the topic_discriminator parameter.
More information
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
required | object |
object | |
Array of objects <= 5 items | |
Array of objects <= 100 items | |
required | Array of objects [ 1 .. 100 ] items |
Responses
Request samples
- Payload
- Curl
{- "keyspace_mapping": {
- "keyspace_discriminator": "com.apsis1.keyspaces.email",
- "field_selector": "email-address"
}, - "options": {
- "update_existing_profiles": true,
- "clear_existing_attributes": true
}, - "consent_mappings": [
- {
- "consents": [
- {
- "resubscribe_if_opted_out": false,
- "field_selector": "mens-clothing-shoes",
- "channel_discriminator": "com.apsis1.channels.email",
- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "type": "opt-in"
}
]
}
], - "tag_mappings": [
- {
- "tag_discriminator": "usercreated.attributes.vip-npqjeo3mbb"
}
], - "attribute_mappings": [
- {
- "field_selector": "address",
- "attribute_version_id": "1234"
}
]
}Response samples
- 201
- 400
- 403
- 404
- 429
- default
{- "import_id": "234345345-c862-4a48-45455-7da1ac0e31ew",
- "file_upload_body": {
- "key": "string",
- "success_action_status": "string",
- "policy": "string",
- "content-type": "string",
- "x-amz-meta-id": "string",
- "x-amz-algorithm": "string",
- "x-amz-credential": "string",
- "x-amz-date": "string",
- "x-amz-signature": "string"
}, - "file_upload_url_expires_at": "string"
}Get profile import status
Get the status of a profile import requested by POST /audience/sections/{section_discriminator}/imports based on import_id
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| import_id required | string |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/imports/%7Bimport_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "import_id": "dsfd45e3-435345-4a48-45455-3435fghfg",
- "result": {
- "status": "completed",
- "profiles_found": 99,
- "profiles_processed": 99,
- "profiles_failed": 0
}
}Request profile in segment by consent export
Profile in segment by consent export
Request an export with profiles that fall into the specified segments and have consented to the particular topics via the specific channels.
Options for consent filtering
This feature supports two methods of specifying channels.
Provide single channel
This option is more automated and recommended when you're interested in consent through a single channel, either email or SMS, for all topics you've provided in the request.
Provide your desired channel in the channel_discriminator request body property.
In terms of columns, the export file contains the attribute corresponding to the channel specified in the request: Email attribute for email channel and Mobile attribute for SMS channel.
As for rows, the export file contains the consented profiles. It also contains profiles that have either not consented to receive or unsubscribed from receiving the communication via that channel (email or SMS) and the topics selected via the request parameters. These records contain blank values in Email or Mobile columns.
Provide multiple channels
This recommended option lets you export consent for multiple channels, email and SMS, in one request. It also gives you more flexibility with the export file contents.
Use the channels request body property to provide a mapping from your desired channels to the export file fields.
In the example below I'm interested in email and SMS consents to any of my topics but I also want to export the email and mobile attribute values:
{
"section_discriminator": "usercreated.sections.europe-r6tz73a27t",
"topic_discriminators": [ "usercreated.topics.bluejeans-cbyntm8qnw", "usercreated.topics.greenjeans-cbyntm8qnw" ],
"channels": [
{ "field_name": "EmailConsent", "channel_discriminator": "com.apsis1.channels.email" },
{ "field_name": "MobileConsent", "channel_discriminator": "com.apsis1.channels.sms" }
],
"attributes": [
{ "field_name": "Email", "attribute_version_id": "1852749" },
{ "field_name": "Mobile", "attribute_version_id": "1852750" }
]
}
The export file for the above request contains email address in the EmailConsent column only for profiles that consented to any of the specified topics via the email channel. Same for MobileConsent and SMS channel.
The other columns, Email and Mobile, are not related to consent. They contain the email and mobile attribute values as requested via the attributes parameter.
| exportKey | EmailConsent | MobileConsent | Mobile | |
|---|---|---|---|---|
| e1ea6ded-61e7-494f-8221-2eb5cf3b2b4d | john@example.com | 41726480987 | john@example.com | 41726480987 |
| d7cdbdf2-b899-4abd-829d-080b93bbc7b7 | karen@example.com | karen@example.com | 48765320019 | |
| 3ff64da9-c436-49df-872d-f40e4a4dee70 | 46895123092 | anna@example.com | 46895123092 | |
| 31e80abd-b890-461f-9e30-e41c87f4d2ff | patrick@example.com | 48700000013 |
In our example John consented to any of the topics via both, email and SMS, and Anna only via SMS.
Excluding unsubscribed profiles
You can use the exclude_unsubscribed_profiles request body parameter to skip the unsubscribed profiles from the export file. If you set it to true, then the profiles that do not currently have an opt-in or confirmed-opt-in consent to any topic from the request via any channel from the request will not be present in the export file.
More on consent types here.
Remaining export file contents
The export file always contains the export key. You can select attributes and tags to include their value as columns in the export file.
For each segments provided in the request body the export file contains a column. These columns are named after the segment names from the request body. A row contains 1 when a corresponding profile matched the segment in question. Otherwise that row says 0.
When exclude_unsubscribed_profiles is true then a subscribed column also appears in the export file. This is for internal use and should not be relied upon by your integration.
How to use
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day.
Call this URL repeatedly with exponential back-off using the same authentication token as for the other APSIS One API calls. Until the result is ready, you will keep getting HTTP 404 Not Found response status code.
As soon as the export file is ready, the poll URL returns HTTP 200 OK and starts streaming a export file as a response.
The HTTP 410 Gone means that the file is no longer available or the ID used is invalid.
Compression
By default the export file is an uncompressed CSV so your code should treat it as .csv. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as .csv.gz.
You can download the same export multiple times using the same poll URL with or without compression.
Additional file format support
By default the export file is a CSV and the Content-Type response header when calling the poll URL is similar to text/csv;charset=UTF-8;header=present. We also support Excel (XLSX) file format. To receive it, provide the Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet request header when calling the poll URL. The response will then contain Content-Type header with the same value.
You can download the same export multiple times using the same poll URL in different file formats.
Limits
Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of topics, attributes and/or tags that is currently not supported.
More information
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
| topic_discriminators required | Array of strings [ 1 .. 100 ] items Topics to which the profiles consented |
| channel_discriminator | string Channel over which the profiles consented. Supported values: |
Array of objects [ 1 .. 2 ] items Channel(s) over which the profiles consented mapped to the export file fields. Cannot be used at the same time as | |
object Allows for including or excluding profiles from the result based on segments. First, provide one or more segments using | |
| duplicate_address_filter | string Exclude duplicate attribute values from the result. Supported
Empty attribute values are not considered duplicate. The time when an attribute value was last updated is considered when comparing via |
Array of objects <= 75 items Attributes to include in the export file | |
Array of objects <= 25 items Tags to include in the export file | |
| limit | integer Limit the export file to a selected number of random profiles |
| exclude_unsubscribed_profiles | boolean You can use the More on consent types here |
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "topic_discriminators": [
- "usercreated.topics.shoes-8u78kijgzn",
- "usercreated.topics.hats-udj7e6ywh3"
], - "channel_discriminator": "com.apsis1.channels.email",
- "channels": [
- {
- "field_name": "EmailConsent",
- "channel_discriminator": "com.apsis1.channels.email"
}
], - "segments": {
- "timezone": "Europe/Stockholm",
- "segment_discriminators": {
- "excludeSentInLast": "usercreated.segments.exclude-send-in-last-rjz6b8td2n",
- "europe": "usercreated.segments.europe-d8jye63u2y",
- "testProfile": "usercreated.segments.test-profile-h27w6td542"
}, - "filter": "(!excludeSentInLast & !exampleDomain) | testProfile"
}, - "duplicate_address_filter": "latest",
- "attributes": [
- {
- "field_name": "First Name",
- "attribute_version_id": "67281"
}
], - "tags": [
- {
- "field_name": "VIP Customer",
- "tag_discriminator": "usercreated.attributes.vip-customer-npqjeo3mbb"
}
], - "limit": 25,
- "exclude_unsubscribed_profiles": false
}Response samples
- 201
- 400
- 413
- 429
- default
Count profiles in segment by consent
Count profiles in segment by consent
Request a count of profiles that fall into the specified segments and have consented to the particular topics via the specific channels.
Options for consent filtering
This feature supports two methods of specifying channels. They're described in detail in the accompanying profile in segment by consent export endpoint description.
How to use
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day.
Call this URL repeatedly with exponential back-off using the same authentication token as for the other APSIS One API calls. Until the result is ready, you will keep getting HTTP 404 Not Found response status code.
As soon as the results are in, HTTP 200 OK will pop up along with the results in the response body. Depending on the data volume on the account, the final call to the poll URL can also take longer.
The HTTP 410 Gone means that the file is no longer available or the ID used is invalid.
The response body of a poll URL call that returns HTTP 200 OK is as follows:
{
"profile_count": 7,
"total_profile_count": 7,
"EmailConsent": 11,
"MobileConsent": 10
}
Note that profile_count is deprecated and replaced by total_profile_count.
Note the two additional properties, EmailConsent and MobileConsent. They are optional and their names come from the original POST request body provided by the user as the values of the field_name property inside the channels array.
Limits
Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of topics, attributes and/or tags that is currently not supported.
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
| topic_discriminators required | Array of strings [ 1 .. 100 ] items Topics to which the profiles consented |
| channel_discriminator | string Channel over which the profiles consented. Supported values: |
Array of objects [ 1 .. 2 ] items Channel(s) over which the profiles consented mapped to the export file fields. Cannot be used at the same time as | |
object Allows for including or excluding profiles from the result based on segments. First, provide one or more segments using | |
| duplicate_address_filter | string Exclude duplicate attribute values from the result. Supported
Empty attribute values are not considered duplicate. The time when an attribute value was last updated is considered when comparing via |
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "topic_discriminators": [
- "usercreated.topics.shoes-8u78kijgzn",
- "usercreated.topics.hats-udj7e6ywh3"
], - "channel_discriminator": "com.apsis1.channels.email",
- "channels": [
- {
- "field_name": "EmailConsent",
- "channel_discriminator": "com.apsis1.channels.email"
}
], - "segments": {
- "timezone": "Europe/Stockholm",
- "segment_discriminators": {
- "excludeSentInLast": "usercreated.segments.exclude-send-in-last-rjz6b8td2n",
- "europe": "usercreated.segments.europe-d8jye63u2y",
- "testProfile": "usercreated.segments.test-profile-h27w6td542"
}, - "filter": "(!excludeSentInLast & !exampleDomain) | testProfile"
}, - "duplicate_address_filter": "latest"
}Response samples
- 201
- 400
- 413
- 429
- default
Request profile in segment event export
Profile in segment event export
Request profile in segment event export. The export can be requested for specific segment or based on event dates and the data can include attributes, tags, events and topic state.
When segment_filter request parameter is provided, only the profiles from the selected segment are exported, otherwise the export file contains all profiles on the account.
Only the attributes, tags and events explicitly declared in the corresponding request parameters are exported. Even though you're only interested in events, you still need to request at least one attribute or tag for the profiles to even show up in the export file.
Time window for events
For events use start_at (mandatory) and end_at parameters to specify the time period for the exported events. When end_at is not provided in a request, it is defaulted to one week after start_at.
Restrain the event time window as much as you can for your use case. Shorter time windows result in faster export processing and smaller export files that are also quicker to transfer and process. This is especially relevant for larger data sets (high number of very active profiles) and when segment_filter with complex queries is used.
How to use
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day.
Call this URL repeatedly with exponential back-off using the same authentication token as for the other APSIS One API calls. Until the result is ready, you will keep getting HTTP 404 Not Found response status code.
As soon as the export file is ready, the poll URL returns HTTP 200 OK and starts streaming a export file as a response.
The HTTP 410 Gone means that the file is no longer available or the ID used is invalid.
In rare cases when the export processing has failed, calling the poll URL returns HTTP 503 Service Unavailable. If that happens, please request a new export with the POST endpoint.
Compression
By default the export file is an uncompressed JSON so your code should treat it as .json. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as .json.gz.
You can download the same export multiple times using the same poll URL with or without compression.
Export file
The export file is in the JSON format.
On the top level there is a JSON dictionary with profiles. The keys in this dictionary are profile export keys.
For each profile, export file contains sections JSON dictionary. The keys in this dictionary are section IDs. Use "Get sections" endpoint of this API to map these IDs to the specific section definitions.
Each section contains both, attributes and tags, inside the attributes JSON dictionary. The keys in this dictionary are IDs of the attributes and tags. Use "Get attributes" and "Get tags" endpoints of this API to map these IDs to the specific attribute and tag definitions. The objects in this dictionary have the following properties:
valueThe data type of this property depends on the attribute type. For tags the value is always
nulland the sheer fact that the attribute exists in the export file means that the corresponding profile was tagged with this particular tag.
If any event type has been requested for a specified section, the corresponding section object also contains events JSON array. Each object in this array represents a single event and contains the following information:
correlationIdID for the event assigned by the event source (Email Tool). The same
correlationIdvalue may be repeated if the event has been sent multiple times due to a retry logic.sourceEventTimeTime of the event in milliseconds since Unix epoch reported by the event source. This feature was introduced at the beginning of 2020 so events prior to that may have
event_timeequal to0. The value of0is also possible when the event source did not specify the event time.typeIdEvent version ID. Use "Get events" endpoint of the API to map these IDs to the specific event definitions.
createdAtTime of the event in milliseconds since Unix epoch as seen on Audience server when it received the event.
dataData specific to a particular event type as defined by "Get events" endpoint of the API
Limits
The export file can include up to 75 attributes and 25 tags. Validated when requesting an export.
Pending export count limit. If reached, HTTP 429 Too Many Requests is returned.
If you request an export with many attributes or a large time window that results in many events, you may receive a status of error when attempting to request or download an export. You can then retry the export request aiming at a smaller data subset.
Usually the errors in processing are caused by:
- using too complex segments
- providing too many attributes and/or tags
- providing too many event types
More information
Authorizations:
Request Body schema: application/jsonrequired
object Select profiles based on an existing segment. Read more in these Help Center articles. | |
Array of objects <= 75 items Attributes to include in the export file | |
Array of objects <= 25 items Tags to include in the export file | |
object Events to include in the export file |
Responses
Request samples
- Payload
- Curl
{- "segment_filter": {
- "timezone": "Europe/Stockholm",
- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1",
- "version_id": "821271"
}, - "attributes": [
- {
- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "attribute_version_id": "67281"
}
], - "tags": [
- {
- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "tag_discriminator": "usercreated.attributes.last-minute-npqjeo3mbb"
}
], - "events": {
- "start_at": "string",
- "end_at": "string",
- "types": [
- {
- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "event_version_id": "725132"
}
]
}
}Response samples
- 201
- 429
- default
{- "file_download_url": "https://exports.api.apsis.one/audience/profiles/exports/e4994c5b-e8fd-48ab-9b1b-9d5d2e6ac378"
}Request single profile export (beta)
Beta
This is a new feature in APSIS One API and we are still keeping a close look on performance and potential issues. Please report any feedback to customerservice.apsis@efficy.com.
Single profile export
Export a single profile, identified by the export key, together with their attribute values (and optionally the change history of these) and events.
This endpoint is asynchronous via callbacks.
How it works
Call this endpoint providing a callback_url which is a public endpoint that accepts HTTP POST requests. For example:
{
"callback_url": "https://example.com/callbacks/single-profile-export"
}
Provided your call is correct, you should receive an empty HTTP 202 Accepted response and after a while your server under callback_url should receive an HTTP POST call with the body similar to the following:
{
"code": 100,
"message": "Callback verified"
}
When we're ready, we will call the callback_url server again and provide it with the URL to fetch the actual data:
{
"code": 200,
"message": "https://api.apsis.one/audience/profiles/export-single/accounts/test/definitions/01af2d3c-d30d-43ec-8f47-996c881148b4?metadata=true"
}
Finally, call that URL with a GET verb and the auth token usually used for APSIS One API to get your export file.
Export file
An example export file follows this structure:
{
"profiles": {
"<export key>": {
"sections": {
"<section ID>": {
"attributes": { },
"events": [ ]
}
}
}
},
"metadata": {
"sections": {
"<section ID>": {
"events": { },
"attributes": { }
}
}
}
}
The profiles object contains the attribute values and event instances that exist in the profile in any section.
The metadata object contains attribute and event definitions for these sections.
If include_attribute_history is set to true the changes to attribute values are also included. They appear inside the attributes object as history.
If include_type_definitions is set to true the export payload also contains the metadata object with type definitions per section.
If include_merged_profiles is set to true more profile keys may appear in the profiles object depending on whether the originally requested profile has been merged or not.
Authorizations:
path Parameters
| export_key required | string Example: 2a3bc7a3-a75f-463c-871d-42f378c019e9 Uniquely identifies a specific profile on the account. You can obtain it from various exports supported by the APSIS One API and from the browser address bar when viewing a profile. |
Request Body schema: application/jsonrequired
| callback_url required | string <uri> Public endpoint that accepts HTTP |
| include_merged_profiles | boolean Include the data of all merged profiles |
| include_attribute_history | boolean Include the data of attribute value changes |
| include_type_definitions | boolean Include the data of type definition per section |
Responses
Callbacks
Request samples
- Payload
- Curl
{- "include_merged_profiles": false,
- "include_attribute_history": false,
- "include_type_definitions": false
}Response samples
- 400
- 404
- 429
- default
{- "status": 400,
- "title": "Bad Request"
}Callback payload samples
{- "status": 200,
- "message": "Export complete",
}Request duplicate profile in segment by consent export
Duplicate profile in segment by consent export
Request an export with profiles that share a specific attribute value.
You can filter the results further by including only the profiles from existing segments or matching provided AQL queries. Provide the existing segments in segment_discriminators or AQL queries in segment_definitions. You also need to send the filter property with a simple logical expression that references the segment discriminator or definition names. You can use either discriminators or definitions. For example:
"segments": {
"timezone": "Europe/Stockholm",
"segment_discriminators": {
"women": "usercreated.segments.women-rjz6b8td2n",
"europe": "usercreated.segments.europe-d8jye63u2y"
},
"filter": "!(europe) & women"
},
The AQL queries can be obtained by calling APSIS One API endpoints that provide them for specific scenarios. For example, to export all profiles who opened a specific email, use the AQL query returned by Get a specific email activity.
You can also filter the results by including only the profiles who subscribed to specific topics. Provide one or more topic_discriminators and channel_discriminator to achieve this. For example:
"topic_discriminators": [
"usercreated.topics.shoes-8u78kijgzn",
"usercreated.topics.hats-udj7e6ywh3"
],
"channel_discriminator": "com.apsis1.channels.email"
The export file always contains the export key. You can select other attributes and tags to include their value as columns in the export file.
Downloading the requested export file
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day. Call this URL repeatedly with exponential back-off using HTTP GET and the same authentication token as for the other APSIS One API calls. You will be getting one of the following responses:
HTTP 404 Not Found- export in progress, the export file is no longer available or the ID provided is invalidHTTP 200 OK- the export file is ready and is immediately streamed as a responseHTTP 410 Gone- the export file is no longer available or the ID provided is invalid
Export file format
The Content-Type response header received when calling the poll URL specifies the export file format. Provide the Accept request header when calling the poll URL to select a different export file format. Supported values for these headers are:
- CSV:
text/csv;charset=UTF-8;header=present(default) - Excel:
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
You can download the same export multiple times using the same poll URL in different file formats.
Export file compression
By default the export file is not compressed so your code should treat it as, depending on the file format, .csv for example. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as, depending on the file format, .csv.gz.
You can download the same export multiple times using the same poll URL with or without compression.
Limits
Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of topics, attributes and/or tags that is currently not supported.
More information
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
| topic_discriminators | Array of strings <= 100 items Topics to which the profiles consented |
| channel_discriminator | string Channel over which the profiles consented to the topics from |
object Provide one or more segments using | |
| find_duplicates_by_attribute_version_id required | string The report will contain profiles that share the value for this attribute. |
Array of objects <= 75 items Attributes to include in the export file | |
Array of objects <= 25 items Tags to include in the export file | |
| limit | integer Limit the export file to a selected number of random profiles |
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "topic_discriminators": [
- "usercreated.topics.shoes-8u78kijgzn",
- "usercreated.topics.hats-udj7e6ywh3"
], - "channel_discriminator": "com.apsis1.channels.email",
- "segments": {
- "timezone": "Europe/Stockholm",
- "segment_discriminators": {
- "excludeSentInLast": "usercreated.segments.exclude-send-in-last-rjz6b8td2n",
- "europe": "usercreated.segments.europe-d8jye63u2y",
- "testProfile": "usercreated.segments.test-profile-h27w6td542"
}, - "segment_definitions": {
- "excludeSentInLast": "section(14230).event(468206).inLast(\"events.hour\",48)",
- "exampleDomain": "section(14230).attribute(404068).contains(\"@example.com\")",
- "testProfile": "section(14230).attribute(404068).contains(\"test@\")"
}, - "filter": "(!excludeSentInLast & !exampleDomain) | testProfile"
}, - "find_duplicates_by_attribute_version_id": "67281",
- "attributes": [
- {
- "field_name": "First Name",
- "attribute_version_id": "67281"
}
], - "tags": [
- {
- "field_name": "VIP Customer",
- "tag_discriminator": "usercreated.attributes.vip-customer-npqjeo3mbb"
}
], - "limit": 25
}Response samples
- 201
- 400
- 413
- 429
- default
Request profile in segment export (beta)
Beta
This is a new feature in APSIS One API and we are still keeping a close look on performance and potential issues. Please report any feedback to customerservice.apsis@efficy.com.
Profile in segment export
Request an export with profiles from an existing segment (using segment_discriminator) or matching a provided AQL query (using segment_definition).
The AQL queries can be obtained by calling APSIS One API endpoints that provide them for specific scenarios. For example, to export all profiles who opened a specific email, use the AQL query returned by Get a specific email activity.
Optionally specify to include known or unknown profiles only.
The export file always contains the export key. You can select other attributes and tags to include their value as columns in the export file.
Downloading the requested export file
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day. Call this URL repeatedly with exponential back-off using HTTP GET and the same authentication token as for the other APSIS One API calls. You will be getting one of the following responses:
When using the poll URL from file_download_url_v2 (in development):
HTTP 202 Accepted- export in progressHTTP 200 OK- the export file is ready and is immediately streamed as a responseHTTP 410 Gone- the export file is no longer availableHTTP 404 Not Found- the ID provided is invalid
When using the poll URL from file_download_url:
HTTP 404 Not Found- export in progress, the export file is no longer available or the ID provided is invalidHTTP 200 OK- the export file is ready and is immediately streamed as a responseHTTP 410 Gone- the export file is no longer available or the ID provided is invalid
Export file format
The Content-Type response header received when calling the poll URL specifies the export file format. Provide the Accept request header when calling the poll URL to select a different export file format. Supported values for these headers are:
- CSV:
text/csv;charset=UTF-8;header=present(default) - Excel:
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - JSON:
application/json(in development)
You can download the same export multiple times using the same poll URL in different file formats.
Export file compression
By default the export file is not compressed so your code should treat it as, depending on the file format, .csv for example. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as, depending on the file format, .csv.gz.
You can download the same export multiple times using the same poll URL with or without compression.
Limits
Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of attributes and/or tags that is currently not supported.
More information
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
required | object Provide a segment using |
| known_profiles | boolean Optional parameter that allows for known and unknown profiles filtering
|
Array of objects <= 75 items Attributes to include in the export file | |
Array of objects <= 25 items Tags to include in the export file | |
| limit | integer Limit the export file to a selected number of random profiles |
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "segment": {
- "timezone": "Europe/Stockholm",
- "segment_discriminator": "usercreated.segments.exclude-send-in-last-rjz6b8td2n"
}, - "known_profiles": null,
- "attributes": [
- {
- "field_name": "First Name",
- "attribute_version_id": "67281"
}
], - "tags": [
- {
- "field_name": "VIP Customer",
- "tag_discriminator": "usercreated.attributes.vip-customer-npqjeo3mbb"
}
], - "limit": 25
}Response samples
- 201
- 400
- 413
- 429
- default
{- "file_download_url_v2": "https://exports.api.apsis.one/audience/profiles/reports/segments/v2/e4994c5b-e8fd-48ab-9b1b-9d5d2e6ac378"
}Count profiles in segment (beta)
Beta
This is a new feature in APSIS One API and we are still keeping a close look on performance and potential issues. Please report any feedback to customerservice.apsis@efficy.com.
Profile in segment count
Request a count of profiles from an existing segment or matching a provided AQL query. Optionally specify to include known or unknown profiles only.
See the corresponding profile in segment export for more information about AQL queries.
More information
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
required | object Provide a segment using |
| known_profiles | boolean Optional parameter that allows for known and unknown profiles filtering
|
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "segment": {
- "timezone": "Europe/Stockholm",
- "segment_discriminator": "usercreated.segments.exclude-send-in-last-rjz6b8td2n"
}, - "known_profiles": null
}Response samples
- 200
- 400
- 413
- 429
- default
{- "profile_count": 7
}Get all recent email activities
Returns all recent email activities. The maximum of 500 recent activities are returned sorted by created_at.
When include_statistics parameter is provided and set to true then activity statistics are also included in the response but only if they have been calculated (e.g. email has been sent).
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_statistics | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/emails/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities?include_statistics=SOME_BOOLEAN_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer campaign sending",
- "status": "sent",
- "created_at": "2017-07-21T17:32:28.761Z",
- "sent_at": "2017-07-21T17:32:28.761Z",
- "email_subject": "Summer sale",
- "statistics": {
- "sent": 6000,
- "delivered": 5900,
- "delivery_rate": 43.3,
- "opens": 4500,
- "unique_opens": 4400,
- "open_rate": 55.2,
- "clicks": 3499,
- "unique_clicks": 3200,
- "click_rate": 44.7,
- "click_to_open_rate": 33.4,
- "bounces": 300,
- "bounce_rate": 20.5,
- "unsubscribes": 100,
- "unsubscribe_rate": 2.3,
- "spam_complaints": 100,
- "spam_complaint_rate": 0.3
}
}
]
}Get a specific email activity
Returns a specific email activity.
Provides AQL queries to build segments that return profiles based on specific criteria. They can be used with profile in segment export.
When include_statistics parameter is provided and set to true then activity statistics are also included in the response but only if they have been calculated (e.g. email has been sent).
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_statistics | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/emails/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae?include_statistics=SOME_BOOLEAN_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer campaign sending",
- "status": "sent",
- "created_at": "2017-07-21T17:32:28.761Z",
- "sent_at": "2017-07-21T17:32:28.761Z",
- "email_subject": "Summer sale",
- "statistics": {
- "sent": 6000,
- "delivered": 5900,
- "delivery_rate": 43.3,
- "opens": 4500,
- "unique_opens": 4400,
- "open_rate": 55.2,
- "clicks": 3499,
- "unique_clicks": 3200,
- "click_rate": 44.7,
- "click_to_open_rate": 33.4,
- "bounces": 300,
- "bounce_rate": 20.5,
- "unsubscribes": 100,
- "unsubscribe_rate": 2.3,
- "spam_complaints": 100,
- "spam_complaint_rate": 0.3
}, - "aql_queries": {
- "sent": "(section(56019).event(1040147).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "delivered": "(section(56019).event(8263452).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "opens": "(section(56019).event(7622133).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "clicks": "(section(56019).event(8273561).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "bounces": "(section(56019).event(3672813).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "spam_complaints": "(section(56019).event(7825113).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "unsubscribes": "(section(56019).event(6712313).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))"
}
}Request email event export
Email event export
Request an export of email events decorated with selected attributes and tags since the specific start_at date, optionally to a specific end_at date.
You can also target a specific segment via the segment_filter property.
Generating an export is an asynchronous operation. Once it's been requested you can check the status and obtain the download link using the corresponding Get email event export status endpoint.
Export file
The following events are included in the export file:
- Sent
- Delivered
- Bounced
- Open
- Clicked
- Unsubscribed
- Reported spam
The export file is a GZIP compressed CSV file containing the following default columns:
activity_idID of the main activity. Activities can have sub-activities in case of split testing.
split_idActivity ID of this event's sub-activity. Same as
activity_idfor non-split sendings and the winning partition in split tests.activity_nameName given to the activity
split_activity_nameName of the split group
senderEmail sender name
subjectEmail subject
addressPrimary email address attribute of the targeted profile (from the same data section as the event)
variationSplit test recipient group. Empty for non-split sendings.
typeEvent type
SENTDELIVEREDOPENEDCLICKEDBOUNCEDUNSUBSCRIBEDABUSE
correlation_idID for the event assigned by the event source (Email Tool). The same
correlation_idvalue may be repeated if the event has been sent multiple times due to a retry logic.event_timeTime of the event in milliseconds since Unix epoch reported by the event source. This feature was introduced at the beginning of 2020 so events prior to that may have
event_timeequal to0. The value of0is also possible when the event source did not specify the event time. The dates in 1970 are possible when the event source specified the event time as0since they're interpreted as Unix epoch.server_timeTime in milliseconds since Unix epoch when the event was received by One
deviceOnly for
CLICKEDandOPENEDevents. Values may be extended with new values and with additional data as suffix.TABLETMOBILEDESKTOPSMART_TVUNKNOWN
locationOnly for
CLICKEDandOPENEDevents. ISO 3166-1 alpha-2. May be extended with new data as suffix.link_idOnly for
CLICKEDevents. ID of the link.link_urlOnly for
CLICKEDevents. URL of the link target.link_titleOnly for
CLICKEDevents. Title given to the link in the email template.bounce_codeOnly for
BOUNCEDevents. Detailed bounce reason.- 1000-1999 Rejected by recipient's server
- 2000-2999 Invalid address (permanent)
- 2001 Email address does not exist
- 2002 Domain of address does not exist
- 2004 Closed email account
- 3000-3999 Address is temporarily unavailable
- 3001 Mailbox is full
- 3002 Recipient server is too busy
- 3003 Email account is inactive
- 4000-4999 Technical delivery problem
- 4003 Network error
- 4007 SPF authentication error
- 4008 DMARC authentication error
- 4009 DKIM authentication error
- 5000-5999 Informational (out of office, auto reply etc.)
- 9999 Unknown failure
unsubscribe_topicOnly for
UNSUBSCRIBEDevents. Discriminator of the unsubscribed topic.abuse_sectionOnly for
ABUSEevents. Discriminator of the abuse.
On top of the default columns the export file contains the fields requested in additional_attribute_mappings property for attributes and additional_tag_mappings property for tags. These have the headers following this pattern: gender (version_id: 491874). When a field is a tag, then the fact of it being set is denoted by the constant TAG in the export file.
In its requests and responses, APSIS One API supports date and time formatted as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.
Date format in the export files follows the type of the attribute. Read more about attribute types in this Help Center article.
Limits
Maximum export time window for events is three months. Validated when requesting a export.
The export file can contain up to 500 attributes and tags in total. Validated when requesting a export.
Pending export count limit. If reached, HTTP 429 Too Many Requests is returned.
Maximum file size limit. If you request a export with very large data set, i.e. many attributes or large time window that results in many events, you may receive a status of error when calling GET /emails/reports/{report_id}. You can then retry the export request aiming at a smaller data subset.
If there are over 25 sections on the account then HTTP 413 Request Entity Too Large may be returned
About events
Events are created in response to actions performed on activities. A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Email activities can be fetched using the following endpoints:
- recent activities:
GET /emails/sections/{section_discriminator}/activities - specific activity:
GET /emails/section/{section_discriminator}/activities/{activity_id}
More information
Authorizations:
Request Body schema: application/jsonoptional
| start_at required | string <date-time> Date and time formatted as ISO 8601 referred to as |
| end_at | string <date-time> Date and time formatted as ISO 8601 referred to as |
object Select profiles based on an existing segment. Read more in these Help Center articles. | |
Array of objects <= 75 items Include profile attributes in this list to receive them as fields in the export file on top of the default event properties | |
Array of objects <= 25 items Include profile tags in this list to receive them as fields in the export file on top of the default event properties |
Responses
Request samples
- Payload
- Curl
{- "start_at": "string",
- "end_at": "string",
- "segment_filter": {
- "timezone": "Europe/Stockholm",
- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1",
- "version_id": "821271"
}, - "additional_attribute_mappings": [
- {
- "field_name": "CRM-ID",
- "section_discriminator": "com.apsis.sections.user-created",
- "attribute_version_id": "67281"
}
], - "additional_tag_mappings": [
- {
- "field_name": "custom-tag-1",
- "section_discriminator": "com.apsis.sections.user-created",
- "tag_discriminator": "usercreated.attributes.export-tag-1-asd69"
}
]
}Response samples
- 201
- 400
- 404
- 429
- default
{- "report_id": "1b59132e-1280-4b33-a096-293b5f42e3ae"
}Get email event export status
Get the status an email event export previously requested using the Request email event export endpoint based on report_id.
Downloading the export file
When the status response property is completed then the export file is ready for download. In such case the response contains the file_download_url property. Use a GET request along with this URL to download the export file.
The file_download_url_expires_at is also provided and instructs you until when the URL is valid. Should you wish to download the same export file multiple times, you need to call this endpoint again to refresh the URL.
Finally, file_expires_at tells you until when the specific export, identified by the report_id, is guaranteed to be kept available for download.
Authentication via headers
Export file download URL is secure. If you wish to further increase its security, you can opt for transmitting the authentication via headers instead of the query string.
To do this, provide the header_auth request query string parameter as true when calling this endpoint.
If you do that, the file_download_url response property does not contain the data required to authenticate the export file download. Instead, a token is returned inside the x-apsis-auth response header.
When attempting to download the file using the URL generated this way you need to provide this token as a x-apsis-auth request header.
Authorizations:
path Parameters
| report_id required | string Example: 1b59132e-1280-4b33-a096-293b5f42e3ae |
query Parameters
| header_auth | boolean Example: header_auth=true When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/emails/reports/1b59132e-1280-4b33-a096-293b5f42e3ae?header_auth=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "report_id": "1b59132e-1280-4b33-a096-293b5f42e3ae",
- "result": {
- "status": "completed",
- "message": "Report generated successfully and is available for download",
- "file_expires_at": "string",
- "file_download_url_expires_at": "string"
}
}Get all recent SMS activities
Returns all recent SMS activities. The maximum of 500 recent activities are returned sorted by created_at.
When include_statistics parameter is provided and set to true then activity statistics are also included in the response but only if they have been calculated (e.g. SMS has been sent).
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_statistics | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/sms/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities?include_statistics=SOME_BOOLEAN_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer campaign sending",
- "status": "sent",
- "created_at": "2017-07-21T17:32:28.761Z",
- "statistics": {
- "sent": 6000,
- "delivered": 5000,
- "delivery_rate": 40.2,
- "clicks": 3000,
- "click_rate": 23.4,
- "bounces": 100,
- "bounce_rate": 100,
- "unsubscribes": 100,
- "unsubscribe_rate": 3.4
}
}
]
}Get a specific SMS activity
Returns a specific SMS activity.
Provides AQL queries to build segments that return profiles based on specific criteria. They can be used with profile in segment export.
When include_statistics parameter is provided and set to true then activity statistics are also included in the response but only if they have been calculated (e.g. SMS has been sent).
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_statistics | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/sms/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae?include_statistics=SOME_BOOLEAN_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer campaign sending",
- "status": "sent",
- "created_at": "2017-07-21T17:32:28.761Z",
- "statistics": {
- "sent": 6000,
- "delivered": 5000,
- "delivery_rate": 40.2,
- "clicks": 3000,
- "click_rate": 23.4,
- "bounces": 100,
- "bounce_rate": 100,
- "unsubscribes": 100,
- "unsubscribe_rate": 3.4
}, - "aql_queries": {
- "sent": "(section(56019).event(1040147).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "delivered": "(section(56019).event(8263452).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "clicks": "(section(56019).event(8273561).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "bounces": "(section(56019).event(3672813).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "unsubscribes": "(section(56019).event(6712313).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))"
}
}Get all recent Website activities
Returns all recent Website activities. The maximum of 500 recent activities are returned.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/website/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Cookie banner",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "active"
}
]
}Get a specific Website activity
Returns a specific Website activity.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/website/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Cookie banner",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "active"
}Get all recent Marketing Automation activities
Returns all recent Marketing Automation activities. The maximum of 500 recent activities are returned.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| trigger_types | Array of strings (TriggerType) Items Value: "api" If provided in the request, this comma separated list of trigger types will filter the activities in the response. For example By default, activities are not filtered by trigger types. |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/marketing-automation/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities?trigger_types=SOME_ARRAY_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 400
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Confirmation sender",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "finished",
- "description": "Sends confirmations to people who subscribed"
}
]
}Get a specific Marketing Automation activity
Returns a specific Marketing Automation activity.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/marketing-automation/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Confirmation sender",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "finished",
- "description": "Sends confirmations to people who subscribed"
}Get all recent Forms & Pages activities
Returns all recent Forms & Pages activities. The maximum of 500 recent activities are returned.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/forms-and-pages/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer sale subscription form",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "active"
}
]
}Get a specific Forms & Pages activity
Returns a specific Forms & Pages activity.
For forms, provides AQL queries to build segments that return profiles based on specific criteria. They can be used with profile in segment export.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
As soon as a form is saved as draft or published, the elements array in the response body contains the elements added to the form.
Authorizations:
path Parameters
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/forms-and-pages/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer sale subscription form",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "active",
- "elements": [
- {
- "type": "input_field",
- "id": "dd026b6b-f01a-4ace-b777-86443eb27457",
- "name": "My input field element",
- "required": false,
- "placeholder": "Type your email address",
- "confirm_placeholder": "Confirm your email address",
- "confirm": true
}
], - "aql_queries": {
- "viewed": "(section(56019).event(1040147).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "started": "(section(56019).event(8263452).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "rejected": "(section(56019).event(7622133).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "submitted": "(section(56019).event(8273561).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))"
}
}Opt-out all (in development)
🚧 In development
This APSIS One API feature is in development and it's not meant to be used yet
Opt-out all
Stops any marketing communication from the APSIS One platform towards a specific profile.
For a given profile specified by keyspace_discriminator and profile_key, looks for opt-in and confirmed-opt-in consents created to any topic via any channel on any section and changes them to opt-out.
HTTP 404 Not Found is returned when a keyspace or profile is missing.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Responses
Request samples
- Curl
curl --request DELETE \ --url https://api.apsis.one/v2/audience/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com/consents/opt-out-all \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 403
- 404
- default
{- "status": 403,
- "title": "Forbidden",
- "detail": "Profile access via One API is not allowed through this keyspace"
}Send a Transactional Email (in development)
🚧 In development
This APSIS One API feature is in development and it's not meant to be used yet
Send a Transactional Email
Sends an existing Transactional Email activity to a single email address provided via the to_email request parameter. This action is also called a transaction.
Sending a transaction generates transactional events related to email sending like "sent", "delivered", "open", etc. These events are created on a profile designated with keyspace_discriminator and profile_key request parameters. If a profile does not exist it is implicitly created.
To work with existing profiles and/or to have access to transactional events, use keyspaces like com.apsis1.keyspaces.email or com.apsis1.keyspaces.crm-id.
If you're not interested in these events, it's best to use com.apsis1.keyspaces.transactional-email keyspace.
Variables and attachments
Keep variables short as they're meant to replace short amounts of text in your transactional email.
If your email gets large, in the ballpark of megabytes, consider using attachments instead.
Don't embed images. Upload your images to APSIS One image gallery or your own hosting and link to them in your transactional email activity or variables.
Variables data types
Currently supported data types which can be used in transactional email editor and when sending transactional emails:
- String
- Number (integer)
- Date
Variables created as type Date in email editor should be provided as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.
Data types planned for future:
- HTML fragment
- Date and time without time zone
- Number with decimal
Limits
The total size of all variables including their names must not exceed 200 kB.
The total size of all attachments must not exceed 2 MB.
It is not recommended, but if for some reason you are planning to merge profiles from com.apsis1.keyspaces.transactional-email keyspace with other profiles then be aware of the limitation of 500 profiles that can be merged together. For this reason we DO NOT recommend to create multiple transactional profiles in com.apsis1.keyspaces.transactional-email keyspace and then merge them with other profiles. Instead, use that other keyspace when sending transactional emails.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| transactional_activity_id required | string Example: 57cf9b7d-7cb1-4385-b4de-e3d01a3deca4 The ID of Transactional Email or Transactional SMS activity. Not to be confused with the specific sending (transaction) ID. |
Request Body schema: application/jsonrequired
| keyspace_discriminator required | string Sending a transaction generates events. The |
| profile_key required | string Sending a transaction generates events. The |
| to_name required | string Display name to which this transaction is sent |
| to_email_address required | string <email> Email address to which this transaction is sent |
| from_name | string Sender display name. If one is not provided in the request we will fall back to the value from the activity. |
| from_email_address | string <email> Sender email. If one is not provided in the request we will fall back to the value from the activity. |
| reply_email_address | string <email> Reply email. If one is not provided in the request we will fall back to the value from the activity. |
| subject_line | string Email subject. If one is not provided in the request we will fall back to the value from the activity. |
| pre_header | string Email pre-header. If one is not provided in the request we will fall back to the value from the activity. |
object Object representing the values for the variables used in the transactional email body. These values are used for this specific sending. The object can be obtained from the activity view in APSIS One. Currently supported data types which can be used in transactional email editor and when sending transactional emails:
Variables created as type Date in email editor should be provided as ISO 8601 referred to as Data types planned for future:
| |
Array of objects <= 5 items Files that are attached to the email. A maximum of 5 attachments is allowed. The |
Responses
Request samples
- Payload
- Curl
{- "keyspace_discriminator": "com.apsis1.keyspaces.transactional-email",
- "profile_key": "a6a1293d-74e9-49eb-a9d0-582820d55ec2",
- "to_name": "John Doe",
- "to_email_address": "john.doe@example.com",
- "from_name": "Heartland Orders",
- "from_email_address": "orders@heartland.com",
- "reply_email_address": "orders@heartland.com",
- "subject_line": "Your order is confirmed",
- "pre_header": "We have received your order and are now processing it",
- "variables": {
- "customer-name": "John Doe",
- "order-number": 76254412,
- "order-date": "2017-07-21T17:32:28.761Z"
}, - "attachments": [
- {
- "name": "invoice.pdf",
- "content_type": "application/pdf",
- "content": "QVBTSVMgT25lIEFQSQ=="
}
]
}Response samples
- 201
- 400
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}Get a Transactional Email sending status (in development)
🚧 In development
This APSIS One API feature is in development and it's not meant to be used yet
Get a Transactional Email sending status
Find out about the status of a specific sending of a specific Transactional Email to a specific address
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| transactional_activity_id required | string Example: 57cf9b7d-7cb1-4385-b4de-e3d01a3deca4 The ID of Transactional Email or Transactional SMS activity. Not to be confused with the specific sending (transaction) ID. |
| transaction_id required | string Example: 7c7bcde1-0168-4726-863b-a923356e2774 The ID of a specific sending of a specific Transactional Email or Transactional SMS activity. Not to be confused with the activity ID. |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/emails/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/57cf9b7d-7cb1-4385-b4de-e3d01a3deca4/transactions/7c7bcde1-0168-4726-863b-a923356e2774 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "status": "sent"
}Introduction
This section provides an explanation of the errors which can be expected from most of the endpoints in APSIS One API.
AUD-10 Request has timed out
The request has timed out due to reaching the service time limit. Please try again and if the error persists, please contact customerservice.apsis@efficy.com.
AUD-1201 Profile not found
AUD-1202 Profile locked
The profile is locked so it cannot be used. However, it can be deleted and recreated again.
AUD-1203 Profile update unauthorized
The provided keyspace is not authorized to update the profile.
AUD-1204 Profile is too large
The profile update exceeds the update size limit. Please contact customerservice.apsis@efficy.com for further assistance.
AUD-1205 Merge limit reached
The profiles cannot be merged as the combined size of the merge cluster would exceed the cluster size limit. Please contact customerservice.apsis@efficy.com for further assistance.
AUD-1206 Merge blocked
The profiles could not be merged as one or more blocking attributes, for example email, had conflicting values.
AUD-1207 Attribute was not set
The attribute was not defined for the profile.
AUD-1208 Deprecated type is not allowed
The type is deprecated and cannot be used for profile updates.
AUD-1209 Write permission is not granted for this type in the used keyspace
Write operations are not granted for the type using this keyspace. Permission can be granted in settings->sections->data model.
AUD-1210 Provided value incompatible to data type
The value provided for the type does not conform to the form expected by the type definition.
AUD-1211 Unmerging a canonical profile is not allowed
This profile is canonical: it is the combined view of all profiles merged together. Only non-canonical profiles in a merge cluster can be unmerged.
AUD-1212 Too many requests to database
The server received too many operations and reached its service limit. Please try again later.
AUD-1213 Request capacity limit reached
The server reached its request capacity limit. Please try again later.
AUD-1214 Database queue exhausted
The queue for database operations has been exhausted. Please try again later.
AUD-1215 Invalid type definition provided
The provided type definition was invalid.
AUD-1216 Throttled cache update
Requests to the underlying cache system were throttled. Please try again later.
AUD-1217 Failed to update cache
The underlying cache system failed to update. Please try again later.
AUD-1218 Profile data cannot be empty
The profile data is mandatory and cannot be empty.
AUD-1400 Invalid type definition
Received an unexpected field type from a type stored in One. This is a sign of an invalid account setup or out of sync servers. Please contact customerservice.apsis@efficy.com if the error persists.
AUD-1402 No such field
The given path does not point to a corresponding data point in the specified type.
AUD-1403 Set/List types are not supported
Data types containing an array [] marker is currently not supported
AUD-1404 Not a primitive type
Field conditions are only supported on primitive types. The given path points to a node of struct type.
We support section(1).attribute(2).attributeData("fieldLevel1").attributeData("fieldLevel2").eq("string") but not section(1).attribute(2).attributeData("fieldLevel1").eq("string") for data type:
{
"fieldLevel1" : {
"fieldLevel2" : "string"
}
}
AUD-1405 Invalid channel communication
The provided communication type is not valid for the specified channel.
AUD-1406 Invalid requested consent value
The requested consent state value is not supported.
AUD-1407 Channel not found
Channel ID could not be found.
AUD-1408 Full section access required
GDPR export is only available for users with access to every Section in the account.
AUD-1409 Callback unreachable
The provided callback uri is unreachable from the service.
AUD-1410 Unexpected callback response
The callback response returned an unsuccessful status code, indicating failure.
AUD-1411 Invalid export key
The provided export key is not a valid profile export key.
The export key must follow the expected format [a-zA-Z0-9\-]*.
AUD-1412 Discriminator and version id mismatch in segment AQL reference
The version id belongs to a different segment discriminator than the one provided.
AUD-1413 Account export limit reached
You reached the maximum number of pending export requests for this account. Wait for any running exports to complete before trying this request again.
AUD-1414 Export service limit reached
There are currently too many outstanding export tasks. You reached the shared service limit. Wait and retry later.
AUD-1415 Invalid time zone
The system was unable to recognise the provided time zone.
AUD-1416 Request body validation failed
The request body provided does not contain the expected fields or data.
AUD-1417 Mandatory Field is Missing
- The timezone field is mandatory and should contain a valid timezone identifier, such as Europe/Stockholm.
- The events field is mandatory.
AUD-1420 Query Size Limit Reached
The query size generated by the request reached service limit.
AUD-1423 Invalid Request
- The attribute with the specified ID could not be found in the given section ID.
- The key indexed for the attribute with the specified ID could not be located in the given section ID.
- The requested provider could not be found or is invalid.
- The attribute with the specified ID in the given section ID uses an unsupported type.
- The filter contains identifiers for unknown segments that do not match any defined segment.
- The callback URL is mandatory and must be provided.
- The callback URL must be an absolute URL with either an
httporhttpsscheme. - The value in the URL could not be parsed correctly.
- Two types share the same ID but are assigned different categories in the external data source.
- Multiple categories share the same ID in the external data source provider.
- A category is missing for the type with the specified ID in the external data source provider.
- The
eventsproperty is missing and must be provided. - Error occurred while parsing at the specified line and column.
- Expected an object with export column headers as field names and values as defined in the expected section.
- The export definition should contain a non-null
showDuplicateByfield. - The export definition should contain a non-null
topicsfield.
AUD-1425 Failed to Get Meta Data
MetaData not found or failure in retrieving metadata.
AUD-1427 Failed to Get Consent Data
- The consent process failed.
- The consent process failed due to a proxy issue.
AUD-1429 Invalid Provider
Failed to register external data source provider.
AUD-1430 Provider Registration Failed
Failed to register external data source provider.
AUD-1601 No address to consent
The profile does not have the required address to consent on it.
The email, phone or cookie id attribute depending on consented channel must have a value in the section of the consented topic.
AUD-1602 Consent bad request
The request has invalid data.
AUD-1603 Consent already in pending state
The current consent state is already pending state.
AUD-1604 New consent state is in conflict with the existing state
AUD-1605 New consent state and existing state are the same
AUD-1606 Channel does not support consent
AUD-1607 Topic is bonded to a different channel that does not support this consent
The topic has a channel that is different from the channel provided in the consent request.
AUD-1608 Too many consent updates in a single request
The number of consent updates in the request exceeds the maximum allowed.
AUD-1609 Multiple consent updates for same topic and channel
The request contains conflicting consent updates for the same topic and channel.
AUD-1621 Topic not found
AUD-1622 Topic already exists
AUD-1623 Target not found
Provided target is not found.
AUD-1631 No channel found
AUD-1632 Channel already exists
AUD-1703 Keyspace not found
AUD-1710 Unknown section
Section with ID could not be found.
AUD-1712 Event not found
AUD-1713 Attribute not found
Attribute with ID could not be found in given Section ID
AUD-1714 Type definition is mandatory
The type information must be submitted in the request.
AUD-1715 Invalid type definition
The type definition submitted does not conform to the API specification.
AUD-1716 Only one active version is allowed
There already exists an active version for the type. You must deprecate the current active version before promoting a new version.
AUD-1717 Failed to create type
Failed to create the resource type. Please contact customerservice.apsis@efficy.com if the error persists.
AUD-1718 Unsupported render hint and type
The combination of render hint and type is not supported.
AUD-1719 Type with conflicting definition exists
A type with same discriminator but different specification exists
AUD-1720 Render hint is not supported
Render hint is not supported. You may use one of the primitive types having predefined render hint.
AUD-1721 Authentication flow is not allowed
The authentication flow is not supported.
AUD-1722 Delete event not bootstrapped
The delete event is missing for the section. Please contact customerservice.apsis@efficy.com to re-bootstrap the section.
AUD-1723 Event type versions not found
Type versions for the event were not found.
AUD-1724 One.legacy_instant_seconds is not supported
One.legacy_instant_seconds cannot be used for creating new types.
AUD-1725 List type is not supported
Creating a type from a List is not supported.
AUD-1726 Internal event not bootstrapped
An internal event is missing for the section. Please contact customerservice.apsis@efficy.com to re-bootstrap the section.
AUD-1731 Invalid value for Days of Retention
The value for days of retention must be between 0 and 29220, inclusive.
AUD-2700 Unexpected start of expression
An unexpected start of expression occurred, preventing the completion of the current expression or the proper initiation of a new term, likely due to syntax errors or incomplete structure.
AUD-2701 Invalid section specifier
Invalid section specifier: a natural number matching the ID of the data section is expected but was not provided or was incorrect.
Expected syntax:
section(2345)
AUD-2702 Invalid attribute specifier
Invalid attribute specifier: a natural number matching the version ID of the target attribute is expected but was not provided or was incorrect. Expected syntax:
section(2345).attribute(6789)
AUD-2703 Section specifier should be an integer
Only section IDs (natural numbers) are valid as section specifiers; section names or discriminators are not accepted.
Expected syntax:
section(2345)
AUD-2704 Expected a section id
Expected a section ID, such as section(1), but the provided input was invalid or in the wrong format.
AUD-2705 Expected zero or more attribute field specifiers
Expected zero or more attribute field specifiers, such as .attributeData("field"), followed by field data conditions or the end of the term.
AUD-2706 Unexpected token
Unexpected token, did you mean one of:[end of expression, &&, ||,
.attributeData, .eventData or data conditions(.eq,.lt...)]?
An error occurred due to an unexpected token in the expression. This could be the result of a missing or incorrect syntax.
End of expression: The expression might need to terminate here.
- Logical operators: You may want to use one of the logical operators such as
&&(AND) or||(OR). - Attribute data: You can reference
.attributeDataif you are working with attributes. - Event data: Alternatively, you can reference
.eventDatafor events. - Data conditions: You may also want to apply a data condition, such as
.eq(equals),.lt(less than), and others.
AUD-2707 Invalid attribute id
Only attribute version IDs (natural numbers) are valid as attribute specifiers; attribute names or discriminators are not accepted.
Expected syntax:
section(2345).attribute(6789)
Invalid syntax:
section(2345).attribute("6789")
section(2345).attribute("section name")
section(2345).attribute("com.apsis1.section.discriminator")
AUD-2708 Missing attribute specifier
Missing attribute specifier, such as .attribute(id) after section(id)
Expected syntax:
section(2345).attribute(6789).attributeData("field").eq("value")
Invalid syntax:
section(2345).attributeData("field").eq("value")
AUD-2709 Missing event specifier
Missing event specifier, such as .event(id) after section(id)
Expected syntax:
section(2345).event(6789).eventData("field").eq("value")
Invalid syntax:
section(2345).eventData("field").eq("value")
AUD-2711 Error parsing event field specifiers
Expected zero or more event field specifiers, such as .eventData("field"), followed by field data conditions or the end of the term.
AUD-2712 Invalid event specifier
An invalid event specifier was provided.
- The specifier must be a natural number that matches the version ID of the target event.
- Only event version IDs (natural numbers) are valid as event specifiers — event names or discriminators cannot be used.
Expected syntax:
section(2345).event(6789)
Invalid syntax:
section(2345).event("6789")
section(2345).event("section name")
section(2345).event("com.apsis1.section.discriminator")
AUD-2714 Invalid attribute expression
Expected attributeData selectors, not eventData, for attribute expressions.
Expected syntax:
section(2345).attribute(6789).attributeData("fieldName")
Invalid syntax:
section(2345).attribute(6789).eventData("fieldName")
AUD-2715 Invalid field specifier
Fields must be specified using string literals; missing or unmatched double quotes are prone to causing this error.
AUD-2718 Invalid event expression
Expected eventData selectors, not attributeData, for event expressions.
Expected syntax:
section(2345).event(6789).eventData("fieldName")
Invalid syntax:
section(2345).event(6789).attributeData("fieldName")
AUD-2719 Missing field condition
A condition (e.g., .eq, .lt) is missing for the specified field.
AUD-2720 Invalid parameter
Expected a string constant, such as "value", or a number.
AUD-2722 Syntax error
Expression does not follow AQL syntax rules.
- Syntax error, expected one of [
minute,hour,day,week,month] - Expected a date (1969-07-20) [YYYY-MM-DD] or a date time (1969-07-20 20:17:00) [YYYY-MM-DD hh:mm:ss]
AUD-2724 Attribute is mandatory for external queriesr
Missing Attribute for external queries
AUD-2725 Negative frequency
Valid options include:
- Frequency must be a positive integer.
- Frequency min must be a positive integer.
- Frequency max must be a positive integer.
- Frequency min and max must be a positive integer.
AUD-2726 Invalid frequency
Expects a positive integer
AUD-2727 InLast error
Expected syntax .inLast("events.{minute, hour, day, week, month}", 3, 0)
AUD-2728 BetweenDates error
Expected syntax .betweenDates("events","1970-01-01", "1970-01-01")
AUD-2729 Multiple event error
Expected only one event() in the event expressions.
AUD-2731 Unexpected parse error
Unsupported or invalid expressions in the filter or AQL statement.
AUD-2731 Invalid URI for external data source
Given string uri is not a valid URI.
Expected format:
integrations:///datafetcher/v1/accounts/demo/sections/1/integrations/crm/external_segments/123abc/records?fields=record_id,1
Invalid format:
integrations://datafetcher/v1/accounts/demo/sections/1/integrations/crm/external_segments/123abc/records?fields=record_id,1
datafetcher/v1/accounts/demo/sections/1/integrations/crm/external_segments/123abc/records?fields=record_id,1
integrations:datafetcher/v1/accounts/demo/sections/1/integrations/crm/external_segments/123abc/records?fields=record_id,1
AUD-2900 Invalid account id
Invalid format for the provided account id. Maybe the account name was supplied instead of the id?
AUD-2901 Invalid keyspace id
Expected a positive integer for keyspace id.
AUD-2902 Unacceptable audience
The audience of the JWT is not recognized by this service
AUD-2903 Not authorized for the account
The authorization header is authenticated for a different account than that of the requested resource
AUD-2904 Missing authorization header
Request should have a signed bearer token passed in the authorization header
AUD-2905 Invalid authorization header prefix
The authorization header is expected to start with Bearer
AUD-2906 Invalid authorization header
The value in the authorization header could not be decoded
AUD-2907 Unauthorized for keyspace
Access denied for keyspace used in request
AUD-2908 Unauthorized for section
Access to the requested section was denied.
AUD-2909 Expired authorization token
The signed authorization header has expired and must be renewed before the request can be retried.
AUD-2910 Invalid section id
Expected a positive integer for section id.
AUD-2911 A possible attack as our 'kid' was signed with invalid key
Unable to verify the signature. This is usually due to mismatched credentials, incorrect signature generation, or altered request parameters.
AUD-2912 Unexpected claim was found during validation
Missing or invalid claim was found in the token during validation.
AUD-2913 No keys found for provided kid
The JWT was signed with a Key ID that is not present in the JWKS provided by the authorization server.
AUD-3100 Invalid Sec-WebSocket-Protocol
The system couldn't parse the Sec-WebSocket-Protocol value to int64.
AUD-3101 Expired Sec-WebSocket-Protocol token
The token in the Sec-WebSocket-Protocol header is either invalid or has expired.
AUD-3102 Unknown proxy path
The proxy address does not match any connected client.
AUD-3300 Encryption or Decryption Failed
Internal encryption of sensitive data has failed. Please try again later.
AUD-3301 Invalid Data Provider URL
The URL for external data provider is given in the wrong format.
AUD-3302 Data Provider URL Not Found Or Expired
The requested data provider cannot be found. The provider registration may have expired.
AUD-3303 Unreadable Data Source
One of the used data sources are unreadable.
AUD-3304 Broken stream
Data stream from the data provider was broken before it was fully read.
AUD-3305 Unable to fetch from External Data Provider
Failed to fetch data from the requested data provider.
✉️ Have questions?Contact customerservice.apsis@efficy.com to learn more
Introduction
This page provides answers to frequently asked questions about Profiles.
How do I remove a specific profile key from a merged profile
You may find yourself in a situation where you have a merged profile with two or more unique identifiers (profile keys in multiple keyspaces) and need to remove one of these identifiers (profile keys) while still retaining all the profile attributes, tags and events from all the merged profiles. Follow these steps:
- Unmerge the profile key you need to remove using Unmerge a profile
- Remove the profile key using Delete a profile
To emphasize, this only removes the profile key and does NOT remove any profile attributes, tags or events from any data section.
✉️ Have questions?Contact customerservice.apsis@efficy.com to learn more
Introduction
Subscriptions, a core feature of the APSIS One platform, provide ways to manage the communication preferences of your Profiles. This Help Center article describes the Subscriptions in more details.
⚠️ Subscriptions is the same as ConsentsIn APSIS One API the Subscriptions feature is called Consents feature. Subscription in APSIS One UI is the same as topic in APSIS One API.
Use cases
If you just want a profile to receive communication then add an opt-in consent to a specific topic over a specific channel to that profile.
This section elaborates on APSIS One API use cases related to Subscriptions.
Getting a list of available topics
Call Get topics (version 2) to get all topics available in your section (across all folders).
Identifying topics with the same names across folders
If your folder and topic (subscription) structure is such that your topic names are not unique within your section then you may run into a problem identifying them using just Get topics (version 2) endpoint. In such case there are two solutions:
- Go to APSIS One and edit your subscriptions to change the names of the topics. This way the information provided by Get topics (version 2) should be sufficient to uniquely identify the topics.
- You may have reasons not to rename your topics. The model returned by Get topics (version 2) contains
folder_discriminator. Use it with Get all topic folders to identify the folders to which your topics belong.
Providing consent
Call Create a consent (version 2) to provide a consent for a profile over a specific channel. This can be an opt-in or opt-out consent to a specific topic.
⚠️ Consent is given on a profile levelConsents are created on a profile level. In APSIS One profiles are identified by a keyspace and profile key. For example,
john.doe@example.comcan be a profile key incom.apsis1.keyspaces.emailkeyspace.
Checking existing consents
Call Get consents (version 2) to get topics with consents of specific types for a profile.
Changing profile email or phone number
The APSIS One platform enables your profiles to provide consent to receive communication from you. Consent is created using a selected communication channel: email, SMS or both. Each of these channels has a corresponding profile attribute: email and mobile, respectively. So when a profile consents to receive information from you over the email channel, the platform will use their primary email address attribute when sending emails.
Call Set attributes on a profile (version 2) to change their email or phone number (we will refer to them as addresses from now on). Set attributes on a profile (version 2) automatically moves consent from the original address to the new one.
Importing profiles
Profile import (version 1) is deprecated, we suggest switching to new Profile import (version 2) endpoint.
Common errors
No address to consent
If you get the following error message from Create a consent (version 2) then your profile does not have a value for the attribute corresponding to the channel over which you want to create a consent. Ensure your profile has an Email (or Mobile) attribute set before attempting to create consent over the Email (or SMS) channel.
{
"status": 400,
"title": "No address to consent",
"type": "https://developer.apsis.com/#tag/Error-codes#aud-1601",
"status_code": 400
}
✉️ Have questions?Contact customerservice.apsis@efficy.com to learn more