Anonymised UserSync API Documentation

Purpose

The UserSync API enables partners to create audiences (which we refer to as segments), populate them with members, and publish them for monetisation. There are also endpoints for status reporting

Overview

The Segment Membership API allows you to upload and manage membership data for segments. This API enables you to:

Upload membership lists (provider IDs) for specific segments
Track upload status and processing
Retrieve active membership data
View upload history

Prerequisites

A company created in the system.
A user account in the company.
The partner should have already synchronised partner IDs, via a domain, with Anonymised.

Contact your client success manager or support for these.

Overall Workflow

Login as a user to obtain an access token.
Create a segment.
Upload membership data to the segment.
Check the upload status of a segment, either:
1. Historic (all)
2. Single
Publish the segment.
Get active membership data.

Note:

You can upload file to created or published segments.
If the segment is not published, the uploaded data will be used once the segment is published.
If the segment has already has uploaded data, the new upload will replace the existing data upon successful processing.

Endpoints

Login as a user

Authenticate and obtain a token

https://customer-service.anonymised.io/api/public/v3/login

Request (Post)

BASH

curl --location 'https://customer-service.anonymised.io/api/public/v3/login' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Origin: https://account.anonymised.io' 
--data-raw '{
  "email": "email@test.com",
  "password": "password"
}'

Response (JSON)

JSON

{
  "token": "test_token"
}

Create a segment

Create a segment and obtain the identifier

https://customer-service.anonymised.io/api/public/v3/segment

Request

BASH

curl --location 'https://customer-service.anonymised.io/api/public/v3/segment' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Bearer {token}' 
--data '{
    "name": "Test Segment 727d7fae-aae9-4c8f-96d5-6284ca213fb9",
    "durationDays": 365,
    "type": "core"
}'

Response (JSON)

JSON

{
  "id": 11107,
  "companyId": 1,
  "createdAt": "2025-11-17T10:46:03.545437Z",
  "durationDays": 365,
  "name": "Test Segment a2921e4b-c0b5-45ec-916f-83deee746e6d",
  "publicName": "",
  "size": 0,
  "status": "created",
  "type": "core"
}

Publish the segment

Make a segment live and available for monetisation

https://customer-service.anonymised.io/api/public/v3/segment/{id}/publish

Request (Post)

BASH

curl --location --request POST 'https://customer-service.anonymised.io/api/public/v3/segment/{id}/publish' 
--header 'Accept: application/json' 
--header 'Authorization: Bearer {token}'

Where

{id} is the segment Id from the previous response.

Response (JSON)

JSON

{
  "id": 11107,
  "activatedAt": "2025-11-17T10:46:58.772242Z",
  "companyId": 1,
  "createdAt": "2025-11-17T10:46:03.545437Z",
  "durationDays": 365,
  "name": "Test Segment a2921e4b-c0b5-45ec-916f-83deee746e6d",
  "publicName": "ANON-TEST-1-00931",
  "status": "published",
  "type": "core",
  "externalId": "11968"
}

Upload segment membership data

Upload a CSV file containing membership data for a specific segment.

https://customer-service.anonymised.io/api/public/v3/segment/{id}/membership/upload

Request (Post)

CODE

# Basic upload
curl -X POST 'https://customer-service.anonymised.io/api/public/v3/segment/{id}/membership/upload' 
  -H 'Authorization: Bearer {token}'
  -H 'Content-Type: text/csv' 
  --data-binary @membership.csv

# Upload with MD5 verification
MD5_HASH=$(md5sum membership.csv | awk '{print $1}')
curl -X POST 'https://customer-service.anonymised.io/api/public/v3/segment/{id}/membership/upload'
  -H 'Authorization: Bearer {token}''
  -H 'Content-Type: text/csv'
  -H 'X-Content-MD5: $MD5_HASH'
  --data-binary @membership.csv

Where

{id} is the segment Id.

Request Body
CSV file with the following format:

Exactly one column - ‘provider id’ (required)
Each row contains a single provider Id (3rd party identifier)

Example CSV

CODE

provider_id
user123
user456
user789

Response (JSON)

JSON

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "segmentId": 123,
  "status": "pending",
  "uploadedBytes": 1024,
  "recordsCount": 100,
  "fileMD5": "5d41402abc4b2a76b9719d911017c592",
  "createdAt": "2025-12-16T10:30:00Z",
  "updatedAt": "2025-12-16T10:30:00Z"
}

Returns: 201

Status values:

pending - Upload received, waiting for processing
processing - Currently being processed
completed - Successfully processed and activated
failed - Processing failed (check details field for error message)

Errors:

400 Bad Request - Invalid CSV format or MD5 mismatch

CODE

{
  "error": "invalid CSV header: expected exactly one column"
}

413 Request Entity Too Large - File size exceeds maximum allowed

CODE

{
  "error": "file size exceeds maximum allowed size"
}

401 Unauthorized - Invalid or missing token
404 Not Found - Segment not found or segment is not owned by company

List all uploads for a segment

Retrieve all membership data uploads for a specific segment.

https://customer-service.anonymised.io/api/public/v3/segment/{id}/membership/upload

Request (Get)

CODE

curl -X GET 'https://customer-service.anonymised.io/api/public/v3/segment/{id}/membership/upload'
  -H 'Authorization: Bearer {token}'

Where

{id} is the segment Id.

Response (JSON)

CODE

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "segmentId": 123,
    "status": "completed",
    "uploadedBytes": 1024,
    "recordsCount": 100,
    "fileMD5": "5d41402abc4b2a76b9719d911017c592",
    "createdAt": "2025-12-16T10:30:00Z",
    "updatedAt": "2025-12-16T10:35:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "segmentId": 123,
    "status": "processing",
    "uploadedBytes": 2048,
    "recordsCount": 200,
    "fileMD5": "6d41402abc4b2a76b9719d911017c593",
    "createdAt": "2025-12-16T11:00:00Z",
    "updatedAt": "2025-12-16T11:00:30Z"
  }
]

Returns: 200 OK

Get specific upload details

Retrieve details of a specific membership data upload.

https://customer-service.anonymised.io/api/public/v3/segment/{id}/membership/upload{upload id}

Request (Get)

CODE

curl -X GET 'https://customer-service.anonymised.io/api/public/v3/segment/{id}/membership/upload/550e8400-e29b-41d4-a716-446655440000' 
  -H 'Authorization: Bearer {token}'

Where:

{id} is the segment Id, and

{upload id} is the Id of the upload.

Response

CODE

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "segmentId": 123,
  "status": "completed",
  "uploadedBytes": 1024,
  "recordsCount": 100,
  "fileMD5": "5d41402abc4b2a76b9719d911017c592",
  "details": null,
  "createdAt": "2025-12-16T10:30:00Z",
  "updatedAt": "2025-12-16T10:35:00Z"
}

Returns: 200 OK

Response fields:

id (UUID) - Unique upload identifier
segmentId (integer) - The segment ID
status (string) - Upload status (pending, processing, completed, failed)
uploadedBytes (integer) - Size of uploaded file in bytes
recordsCount (integer) - Number of records (excluding header)
fileMD5 (string, optional) - Calculated MD5 hash of the uploaded file
details (string, optional) - Error message if status is "failed"
createdAt (timestamp) - Upload creation time
updatedAt (timestamp) - Last update time

Errors:

404 Not Found - Upload not found or segment mismatch
401 Unauthorized - Invalid or missing JWT token

Get active membership data

Retrieve the currently active membership data for a segment.

https://customer-service.anonymised.io/api/public/v3/segment/{segment id}/membership

Request (Get)

CODE

curl -X GET 'https://customer-service.anonymised.io/api/public/v3/segment/123/membership'
  -H 'Authorization: Bearer {token}'

Where:

{segment id} is the segment Id

Response:

CODE

{
  "segmentId": 123,
  "activeMembershipUploadId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2025-12-16T10:35:00Z"
}

Returns:200 OK

Response fields:

segmentId (integer) - The segment ID
activeMembershipUploadId (UUID) - The ID of the currently active upload
createdAt (timestamp) - When this membership data was activated

Errors:

404 Not Found - No active membership data found for segment
401 Unauthorized - Invalid or missing JWT token

Data Format Requirements

CSV File Format

The uploaded CSV file must meet the following requirements:

Header: The file must have a header row with exactly one column
Data: Each subsequent row must contain exactly one value (the provider ID)
Encoding: UTF-8 encoding recommended
Line endings: Unix (LF) or Windows (CRLF) line endings are supported

Valid CSV Example:

CODE

provider_id
user001
user002
user003

Invalid Examples:

❌ Multiple columns:

CODE

provider_id,name
user001,John

❌ No header:

CODE

user001
user002

File Size Limits

Maximum file size limits are enforced. Contact your system administrator for current limits.

MD5 Checksum (Optional)

For data integrity verification, you can provide an MD5 hash via the X-Content-MD5 header:

CODE

# Calculate MD5 (Linux/Mac)
md5sum file.csv

# Calculate MD5 (Mac alternative)
md5 file.csv

# Calculate MD5 (Windows PowerShell)
Get-FileHash file.csv -Algorithm MD5

Operations

Typical workflow:

Prepare CSV File: Create a CSV file with one column containing provider IDs
Calculate MD5 (Optional): Generate MD5 hash for integrity verification
Upload File: POST the CSV file to the upload endpoint
Monitor Status: Poll the upload details endpoint to track processing
Verify Activation: Check the active membership endpoint to confirm activation

Processing States

CODE

pending → processing → processed
                          ↓
                    processing_failed
              
pending → deletion → deleted
                        ↓
                deletion_failed
              
pending → processing → processed → deletion → deleted
                                      ↓
                              deletion_failed

Where:

pending: Upload received, queued for processing
processing: File is being validated and loaded into the system
processed: File has been processed successfully
processing_failed : An error occurred during processing
deletion: membership in the process of being deleted
deletion_failed: An error occurred during deletion
deleted: membership has been deleted

Error Handling

Common Error Scenarios

Error Code	Scenario	Solution
400	Invalid CSV format	Ensure CSV has exactly one column with header
400	MD5 mismatch	Recalculate MD5 hash or remove X-Content-MD5 header
401	Authentication failed	Verify JWT token is valid and not expired
404	Segment not found	Verify segment ID and company ownership
413	File too large	Reduce file size or contact administrator

Retry Logic

For failed uploads, you can retry by:

Checking the details field in the upload response
Correcting the issue (e.g., fixing CSV format)
Submitting a new upload request

Support

For additional support or questions, please contact your client success manager or support.

Purpose

Overview

Prerequisites

Table of Contents

Overall Workflow

Endpoints

Login as a user

Request (Post)

Response (JSON)

Create a segment

Request

Response (JSON)

Publish the segment

Request (Post)

Response (JSON)

Upload segment membership data

Request (Post)

Response (JSON)

List all uploads for a segment

Request (Get)

Response (JSON)

Get specific upload details

Request (Get)

Response

Errors:

Get active membership data

Request (Get)

Data Format Requirements

CSV File Format

File Size Limits

MD5 Checksum (Optional)

Operations

Typical workflow:

Processing States

Error Handling

Common Error Scenarios

Retry Logic

Support