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
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 |
|
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 |
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 |
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.