User Export

Download user related information from the Audiens platform

Ensure user-id is provided

Before moving forward with this functionality you need to provided Audiens with a user-id. The identifier is important as it will be the link beetwen what Audiens export and your user. You can reach out to your dedicated account to know what are the possible ways to pass the user-id to the Audiens platform.

The user-id can be any field form a Crm/Database id to the mail of the user

For personal identifiable information (email, phone-number etc..) we only accept value hashed in SHA256 format

Data Location

The data will exported weekly into your dedicated S3 bucket, the scaffolding will look like:

s3://audiens.export/{partner_id}/{year}/{month}/{day}/{filename}.json.gz

The partner id will be provided to you during th early stage of the integration and is usually a 3 or 4 digit number example: 987

The export will always provide you wil a full userbase dump even if there are no new information concerning the user.

We also support a daily export for frequently updated user profiles

AWS CLI examples

Following some examples using aws-cli


Check all the files in you export folder:

aws s3 ls --recursive s3://audiens.export/{partner_id}/

Download a single file:

aws s3 cp s3://audiens.export/{partner_id}/2019/03/01/export.json.gz .

Data format

The export will be in the format of a collection of json separated by a line break.

Following the json-schema draft 6:

Please note that partnerId (User.partnerId) inside this export is actually the user-id you provided for this specific user

{
    "$schema": "http://json-schema.org/draft-06/schema#",
    "type": "array",
    "items": {
        "$ref": "#/definitions/User"
    },
    "definitions": {
        "User": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "identifiers": {
                    "$ref": "#/definitions/Identifiers"
                },
                "events": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Event"
                    }
                },
                "partnerId": {
                    "type": "string",
                    "format": "integer"
                }
            },
            "required": [
                "events",
                "identifiers",
                "partnerId"
            ],
            "title": "User",
            "description": "The single user export, representing the aggregated information."
        },
        "Event": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "eventType": {
                    "$ref": "#/definitions/EventType"
                },
                "source": {
                    "$ref": "#/definitions/EventSource",
                    "description": "Event source type"
                },
                "date": {
                    "type": "string"
                },
                "ipAddress": {
                    "anyOf": [
                        {
                            "type": "null"
                        },
                        {
                            "type": "string"
                        }
                    ],
                    "description": "The event's IP address"
                },
                "os": {
                    "anyOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ],
                    "description": "The OS the event was fired from"
                },
                "device": {
                    "$ref": "#/definitions/Device"
                },
                "details": {
                    "$ref": "#/definitions/EventDetails"
                }
            },
            "required": [
                "date",
                "device",
                "eventType",
                "ipAddress",
                "os",
                "source"
            ],
            "title": "Event",
            "description": "The (heterogeneous) event description"
        },
        "EventDetails": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "geolocation": {
                    "anyOf": [
                        {
                            "$ref": "#/definitions/Geolocation"
                        },
                        {
                            "type": "null"
                        }
                    ],
                    "description": "Used by Visit event"
                },
                "pageViewed": {
                    "type": "string",
                    "description": "The URL of the visited page, used by Visit event"
                },
                "trafficSource": {
                    "anyOf": [
                        {
                            "type": "null"
                        },
                        {
                            "type": "string"
                        }
                    ],
                    "description": "The URL of the page from which the user landed, used by Visit event"
                },
                "userAgent": {
                    "type": "string",
                    "description": "The UserAgent that the user used to visit the page, used by Visit event"
                },
                "couponCode": {
                    "type": "string",
                    "description": "Used by order event"
                },
                "orderId": {
                    "type": "string",
                    "description": "Used by order event"
                },
                "total": {
                    "type": "number",
                    "description": "Used by order event"
                },
                "products": {
                    "type": "array",
                    "description": "The list of the order's products, used by order event",
                    "items": {
                        "$ref": "#/definitions/Product"
                    }
                },
                "productId": {
                    "type": "string",
                    "description": "Used by addToCart event"
                },
                "productName": {
                    "type": "string",
                    "description": "Used by addToCart event"
                },
                "productCategory": {
                    "type": "string",
                    "description": "Used by addToCart event"
                },
                "productPrice": {
                    "type": "number",
                    "description": "Used by addToCart event"
                },
                "productQuantity": {
                    "type": "integer",
                    "description": "Used by addToCart event"
                }
            },
            "required": [],
            "title": "EventDetails"
        },
        "EventSource": {
            "type": "string",
            "enum": [
                "Web"
            ],
            "title": "EventSource",
            "description": "Event source type"
        },
        "EventType": {
            "type": "string",
            "enum": [
                "Visit",
                "generic",
                "order",
                "addToCart"
            ],
            "title": "EventType",
            "description": "Event type discriminator"
        },
        "Geolocation": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "latitude": {
                    "type": "number"
                },
                "longitude": {
                    "type": "number"
                },
                "countryCode": {
                    "type": "string"
                },
                "countryName": {
                    "type": "string"
                },
                "regionCode": {
                    "type": "string",
                    "format": "integer"
                },
                "regionName": {
                    "type": "string"
                },
                "city": {
                    "type": "string"
                },
                "zipCode": {
                    "type": "string"
                }
            },
            "required": [
                "city",
                "countryCode",
                "countryName",
                "latitude",
                "longitude",
                "regionCode",
                "regionName",
                "zipCode"
            ],
            "title": "Geolocation",
            "description": "The geo location description, used by Visit event"
        },
        "Product": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Ecommerce product's id"
                },
                "name": {
                    "type": "string"
                },
                "category": {
                    "type": "string",
                    "description": "Ecommerce product's category name"
                },
                "quantity": {
                    "type": "integer"
                },
                "price": {
                    "type": "number"
                },
                "currency": {
                    "anyOf": [
                      {
                        "type": "null"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Product's currency, if available"
                }
            },
            "required": [
                "category",
                "currency",
                "id",
                "name",
                "price",
                "quantity"
            ],
            "title": "Product",
            "description": "Product's details, used by order event"
        },
        "Device": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "category": {
                    "$ref": "#/definitions/DeviceType",
                    "description": "Type of device"
                },
                "brand": {
                    "anyOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ],
                    "description": "The device's brand"
                },
                "model": {
                    "anyOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ],
                    "description": "The device's model name / identifier"
                }
            },
            "required": [
                "brand",
                "category",
                "model"
            ],
            "title": "Device",
            "description": "The details of the device used by the event"
        },
        "DeviceType": {
            "type": "string",
            "enum": [
                "Desktop",
                "Phone",
                "Tablet"
            ],
            "title": "DeviceType",
            "description": "User device's type"
        },
        "Identifiers": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "email": {
                    "description": "Zero or more emails hashed in SHA256 and/or MD5",
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "msisdn": {
                    "description": "Zero or more phone numbers hashed in SHA256",
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "mobileDevice": {
                    "description": "Zero or more mobile advertising identifiers (IDFA/Adid)",
                    "type": "array",
                    "items": {}
                }
            },
            "required": [
                "email",
                "mobileDevice",
                "msisdn"
            ],
            "title": "Identifiers",
            "description": "The data used to identify the visitor"
        }
    }
}