Upload First-Party Segments

The First-Party Segment (FPS) API allows you to create a first-party segment easily through an API. After uploading, 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.

The FPS segments don't generate new users; instead, they group existing users into segments based on their attribute values.

Use Cases

• Assume that you want to pass your custom segment(s) via API to Insider, but do not want to create a segment on Insider One's InOne panel. Thanks to the FPS API, you can manage all segment creation processes from start to finish.

• Let's say you want to target a set of specific user attributes that contain “Store ID” on UCD. You can create a .csv file and name its first column "Store ID" with the corresponding 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 with 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 them to the FPS segment upload field. This way, a snapshot of the people with those Store ID values is generated.

You do not need to include a header row in the CSV file. The attribute name (e.g., "Store ID") has already been specified in the API payload. The values in the CSV file should be listed without a header.

Endpoint and Headers

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

Headers

Body Parameters

Sample Request

Every request to the request endpoint requires a JSON-formatted body containing the necessary parameters.

The sample below displays a request to upload a customer file (CSV) to create or update an FPS segment.

• For default attributes, use their display names.

• For custom attributes, you can use any name without restriction.

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

{
    "segment_name": "My unique segment",
    "valid_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 the 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 in 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 a POST response.

• You can send up to 100 requests per second with the same API Key. If you exceed the rate limit, you will receive a 429 error.

• The file size cannot be more than 50 MB.

• SegmentName can have a maximum of 40 characters.