Upload First-Party Segments

Overview

The First-Party Segment API allows you to easily create a first-party segment through an API. When the uploading process is completed, the segment is automatically created on your First-Party Segment page under Saved Segments. In addition, you can see the results of the segment creation on the callback.

Use Cases

• Assume that you want to pass your custom segment(s) via API to Insider but you do not want to create a segment on Insider's InOne panel. Thanks to FPS API, you can maintain all of the segment creation process through the API from beginning to the end.
• Let's say you want to target a set of specific user attributes that contain “Store ID” on UCD. You can basically create a .csv file and name its column as Store ID with the store ID values. To make these attribute values produce a segment, you can pass this file’s URL to the payload and at the end of the request, you can get the number of users who have these values.

• Assume that you have 17k store owners as your customers. Instead of multi-selecting 17k values under the segmentation filter, you can list those store_id values on a sheet and upload it on the FPS segment upload field. This way, a snapshot of the people having those store id values are generated.

Endpoint and Headers

POST https://contact.useinsider.com/fps/v1/upload

Headers

Body Parameters

Sample Example

Sample Request

Every request made to the request endpoint requires a request body formatted in JSON containing the required body parameters.

curl --location --request POST 'https://contact.useinsider.com/fps/v1/upload' \
--header 'X-REQUEST-TOKEN: acb123' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'Content-Type: application/json' \
--data-raw '{
  "segmentName": "My Segment Name",
  "fileUrl": "https://s3.amazonaws.com/sample_csv_file.csv",
  "callbackUrl": "https://localhost/12345",
  "attributeName": "Email Address"
}'

Sample Responses

200 OK

{
  "statusMessage": "OK"
}

400 Bad Request

{
  "statusMessage": "segment name already in use"
}

401 Unauthorized

{
  "statusMessage": "Unauthorized"
}

405 Invalid Payload

{
    "error": "Invalid Payload."
}

Error Messages

Sample Callback Responses

200 OK

{
    "status": 200,
    "segment_name": "My unique segment",
    "value_values_count": 5,
    "invalid_values_count": 7,
    "total_entered_values": 12
}

• valid_values_count: The number of valid row values for the given attribute in the body.
• invalid_values_count: The number of invalid row values for the given attribute in the body. For example, you tried to map the CSV file given below with the age attribute. Since age attribute is a number, the invalid_values_count will be 2 in this case.
• total_entered_values: the total number of rows in the .csv file.

Limitations

• All functions must be executed with a simple HTTPS POST request.
• The API Key should be provided as the authorization key on the request header. If the key is incorrect, the operation will not be executed and an authorization error will return in the response.
• The value of the X-PARTNER-NAME header should be lowercase.
• callbackUrl needs to accept POST response
• File size cannot be more than 50MB.