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 in the callback.

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

First-Party Segments API vs. Upsert API

• Use the First-Party Segments API to create a segment from existing users based on one attribute supplied in the request.

• Use the Upsert API to create new users or update attributes, events, and other data on user profiles.

If users or their profile attributes must first be created or updated, complete that operation through the Upsert API before using the First-Party Segments API.

Use Cases

• Assume that you want to pass your custom segment(s) via API to Insider One, but do not want to create a segment on Insider One's InOne panel. With the FPS API, you can manage the entire segment creation process 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, name its first column "Store ID," and include 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

202 Accepted

{
  "statusMessage": "Accepted"
}

400 Bad Request

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

401 Unauthorized

{
  "statusMessage": "Unauthorized"
}

400 Invalid Payload

{
    "error": "Invalid Payload."
}

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

Error reference

Use this table to identify and resolve the errors this endpoint returns. Each row shows the status code, the response body you receive, what causes it, and how to fix it.

{
  "statusMessage": "Accepted"
}

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

{"statusMessage": "Partner Name is required"}

{
    "error": "Invalid Payload."
}

{"statusMessage": "Unauthorized"}

{"statusMessage": "Too Many Requests"}

{
  "status_code": 400,
  "message": "the file you are trying to upload has an issue."
}

Limitations

• All functions must be executed with a simple HTTPS POST request.

• Provide the API Key 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 exceed 50 MB.

• SegmentName can be up to 40 characters.