Audience API¶

Using Audience API, you can optionally use a User ID list to create or update an audience.

Using your data or data collected using other services, you can register a user list with Repro and use it as a user segment for marketing.

Note

Only users registered with Repro can be used. If unregistered users are included in the user list, they will not be counted as part of the target users.

Get Started¶

Get the Repro API token¶

To use the Audience API, you need to set the Repro API token

You can find the Repro API Token at SETTINGS > PRODUCT SETTINGS > Credentials

Warning

"REGISTER API TOKEN" makes the current API token unavailable. Once you do this operation, You never use the key again and revert to the previous state.

Audience API v3¶

Currently, Audience API provides the below functionalities. in order to upload the data, the request has to be sent twice to different endpoints. The second request will be exactly same as new creation.

Function	HTTP Method	Endpoint
Create	`POST`	`https://api.reproio.com/v3/audiences`
Update	`PUT`	`https://api.reproio.com/v3/audiences/<audience id>`

We will provide more details on how to send a request in following description.

Note

The pre-signed URL is valid for 5 minutes. Therefore, please initiate a second request within 5 minutes of receiving the first response.

Access limit per unit time¶

Access is limited per time for Audience API.

The limit is set to 15 accesses for every 10 minutes per API token.
When the request is completed, there will be a notification at the X-RateLimit-Limit header showing the maximum number of requests per time.
When the request count exceeds the maximum access number, the following response HTTP Status 429 (Too Many Requests) will appear.

For more information on response headers, please see Push API responses.

Warning

The maximum access number may fluctuate without warning.
The access limit setting value is per API token per function.

For example, the push API and the user profile API use the same API token, but they are different functions, so even if they are requested at the same time, each is counted as one request.

Sample code¶

The sample codes for new creation.

Change the endpoint from the one used for the first request to the one to update.
Change the request method from POST to PUT for the first request.

#!/bin/bash

set -e

API_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AUDIENCES_URI=https://api.reproio.com/v3/audiences

file=$(realpath -e $1)
checksum=$(openssl dgst -md5 -binary ${file} | base64)
content_size=$(stat -c %s ${file})

body=$(cat <<EOF
{
  "name": "my-audience-api",
  "checksum":"${checksum}",
  "byte_size":"${content_size}"
}
EOF
)

# First request
response=$(curl -v -X POST \
                -H "X-Repro-Token: ${API_TOKEN}" \
                -H "Content-Type: application/json" \
                --data "${body}" \
                ${AUDIENCES_URI})
echo $response

# Get the value needed for the second request from the response
url=$(echo ${response} | jq -r .direct_upload.url)
content_type=$(echo ${response} | jq -r '.direct_upload.headers["Content-Type"]')
content_md5=$(echo ${response} | jq -r '.direct_upload.headers["Content-MD5"]')

# Second request
curl -X PUT \
    -H "Content-Type: ${content_type}" \
    -H "Content-MD5: ${content_md5}" \
    --upload-file ${file} \
    "${url}"

echo done

Create New Audience¶

A new audience can be created with 2 steps below.

Execute POST /v3/audiences and obtain pre-signed URL which is required to direct upload to S3.
Execute PUT <pre-signed URL> and upload a file to S3.

First request¶

Endpoint¶

Function	HTTP Method	Endpoint
Create	`POST`	`https://api.reproio.com/v3/audiences`

Request header¶

Header	Description	Optional / Required
Content-Type	Set application/json	Required
X-Repro-Token	Set the token retrieved with Get the API endpoint and Repro API token	Required

Request parameter¶

Field	Description	Optional / Required
name	Audience name.	Required
checksum	The data which is base64 encoded from md5 checksum of the file. This can be calculated with `openssl dgst -md5 -binary hoge.csv \| base64`.	Required
byte_size	File size of files used to create and update audiences	Required

Payload Example¶

{
  "name": "audience name",
  "checksum": "J1h240z2CdsRjz2Et5mnkA==",
  "byte_size": "1024"
}

Response header¶

The response header contains the following values.

Status	Header	Description
Success	`X-RateLimit-Limit`	Access limit per unit time
Success	`X-RateLimit-Remaining`	The number of requests remaining in the current rate limit window.
Success	`X-RateLimit-Reset`	The time at which the current rate limit window resets in UTC epoch seconds. (Unix UTC timestamp)
Request limited	`Retry-After`	The time how long the user agent should wait before making a follow-up request.

The response of succeeded¶

The response body contains belows as a response in JSON format.

Field	Description
response.id	Audience ID
response.name	Audience name
response.direct_upload	An object containing the information needed for the second request
response.direct_upload.url	Endpoint URL for the second request
response.direct_upload.headers	Header information which is required to the second request.

Response body example of succeeded¶

{
  "id": "ym6nnpkd",
  "direct_upload": {
    "url": "https://repro-direct-upload-production.s3.ap-northeast-1.amazonaws.com/Sx9367LtCmGDRdqfUJVjirRv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAITZGHBHURRYGMYHA%2F20200312%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20200312T062037Z&X-Amz-Expires=300&X-Amz-SignedHeaders=content-md5%3Bcontent-type%3Bhost&X-Amz-Signature=ef75a6b81944375822bcd4c2cdabf362bd02ccce5850577917b6b3fe087de0c5",
    "headers": {
      "Content-Type": "text/csv",
      "Content-MD5": "J1h240z2CdsRjz2Et5mnkA=="
    }
  },
  "name": "my-audience-api"
}

Error response¶

The list below contains all status codes and error messages of the responses.

400 Bad Request¶

You have an error in your request. Please check the error message.

The checksum contains an invalid string.

Response body

{
  "error": {
    "messages": [
      "Validation failed: Checksum is invalid"
    ]
  }
}

The byte_size is not specified.

Response body

{
  "error": {
    "messages": [
      "param is missing or the value is empty: byte_size"
    ]
  }
}

401 Unauthorized¶

You don't have Repro API Token set.

Response body

{
  "status": "unauthorized",
  "error": {
    "messages": [
      "Please include your Repro API Token as \"X-Repro-Token\" HTTP header."
    ]
  }
}

403 Forbidden¶

The specified Repro API Token is invalid.

Response body

{
  "status": "forbidden",
  "error": {
    "messages": [
      "Please check your Repro API Token as \"X-Repro-Token\" HTTP header."
    ]
  }
}

404 Not Found¶

The endpoint does not exist.

Response body

{
  "status": "not_found",
  "error": {
    "messages": [
      "Not found."
    ]
  }
}

429 Too Many Requests¶

Too many requests. Please wait the seconds indicated in the Retry-After header and make a follow-up request.

Response body

{
  "status": "too_many_requests",
  "error": {
    "messages": [
      "Too many requests hit the API too quickly."
    ]
  }
}

Second request¶

Endpoint¶

HTTP Method	Endpoint
`PUT`	The value of `response.direct_upload.url` included in the response when the first request was succeeded.

Request header¶

Please specify all of the value of response.direct_upload.headers included in the response as a header if the first request was succeeded.

Request parameter¶

Please set a CSV file to create an audience. The maximum size of file which can be set is 500MB. The file should be a CSV file with each row containing a single user ID as shown below.For example, if you have set qwpeoifjadlskf, zxocjvasdfoiji, and azxcpoqnadslpx as the user ID, the file will be in the following format.

qwpeoifjadlskf
zxocjvasdfoiji
azxcpoqnadslpx
:

The response of succeeded¶

If audience has been successfully created, a response containing the status code 200.

Error response¶

Please refer to this document for the details on error responses.

Receiving an email with import results¶

Once the import is complete, you will receive an email similar to the one below. Go to the URL and check the import results.

Update Audience¶

The audience can be updated with 2 steps below.

Execute PUT /v3/audiences/<Audience ID> and obtain pre-signed URL which is required to direct upload to S3.
Execute PUT <pre-signed URL> and upload a file to S3.

The following steps is the same as Sample code. Please refer to this.In terms of the end point, you can see it from the audience page of dashboard.

Audience API v2 (deprecated)¶

Warning

Audience API v2 was discontinued on August 31, 2021. If you wish to use the API, please use Audience API v3.