API Endpoint Integration for Custom Systems

Overview

In addition to the pre-built vendor integrations, Polaris supports sending automation requests to your own downstream systems via custom API endpoints. This allows you to automatically process privacy requests (lookup, opt-out, and deletion) in your custom applications and databases.

How It Works

When a privacy request is submitted in Polaris, the system can automatically send API requests to your configured endpoints. You'll set up this integration as a custom integration on the API Integrations page, as you would any other vendor. Your system receives the consumer information and request type, processes it accordingly, and returns a response to Polaris indicating the outcome.

Endpoint Types

Polaris sends API requests for three automation pathways:

• Lookup - Verify whether a consumer exists in your system
• Opt-Out - Process a consumer's opt-out/do-not-sell request
• Delete - Process a consumer's data deletion request

Setting Up Custom API Endpoints

Prerequisites

1. A web service with HTTPS endpoints that can receive POST requests
2. An authentication token (Bearer token) for securing the API requests
3. Ability to respond within 30 seconds to API calls

Configuration

When setting up a custom API endpoint integration in Polaris, you'll need to provide:

• Host URL: The base URL of your API service (e.g., https://api.example.com)
• Path Prefix: Optional path prefix for your endpoints (e.g., /privacy)
• Bearer Token: A secure token that Polaris will include in the Authorization header

The full endpoint URLs will be constructed as: {host}{path_prefix}/{pathway}

For example:

• Lookup: https://api.example.com/privacy/lookup
• Opt-Out: https://api.example.com/privacy/opt-out
• Delete: https://api.example.com/privacy/delete

Implementing Custom API Endpoints

Authentication

All API requests include an Authorization header with your configured Bearer token:

Authorization: Bearer <your-configured-token>

You should validate this token to ensure requests originate from Polaris.

Request Format

All API requests use POST with JSON payload:

Headers:

Header	Value
Content-Type	application/json
Authorization	Bearer <token>

Request Body:

{
  "tracker_id": "550e8400-e29b-41d4-a716-446655440000",
  "request_id": "ABC123XYZ",
  "request_type": "lookup | opt-out | delete",
  "consumer": {
    "email": "consumer@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Field Descriptions:

Field	Type	Required	Description
tracker_id	UUID	Yes	Unique internal identifier for this API call
request_id	string	Yes	The privacy request ID as seen in Polaris
request_type	string	Yes	One of: lookup, opt-out, delete
consumer.email	string	Yes	Consumer's email address (primary identifier)
consumer.first_name	string	No	Consumer's first name (may be empty)
consumer.last_name	string	No	Consumer's last name (may be empty)

Response Format

Your endpoint must respond within 30 seconds with a JSON response indicating the outcome.

HTTP Status Codes

Status	Use When
200	Request was processed successfully
400	Invalid request format or missing required fields
401	Invalid or missing Authorization token
500	An error occurred during processing

Success Response (HTTP 200)

Your response should include the following fields:

Field	Type	Required	Description
success	boolean	Yes	Whether the operation succeeded
outcome	string	Conditional	Required for opt-out or delete requests. One of: confirmed, no_data, submitted, or failed
consumer_found	boolean	Conditional	Required for lookup requests. Whether consumer exists in your system. Optional for other request types, but helps skip the lookup step automatically if consumer data is indicated as found
message	string	No	Human-readable status message

Outcome Values:

Outcome	Description	Use When
confirmed	Request processed immediately	Consumer was found and the opt-out/delete was immediately confirmed (not queued)
no_data	Consumer not found	No matching consumer in your system
submitted	Request sent to downstream systems	An opt-out/deletion request was received and queued in downstream systems for this consumer, but those systems may take some time to process. For purposes of Polaris, this is reflected in the workflow as a successful outcome labelled "Request automatically sent"
failed	Operation failed	An error occurred during processing (specify in message)

Pathway-Specific Examples

Lookup Request

Purpose: Determine if a consumer exists in your downstream systems.

Example Response - Consumer Found:

{
  "success": true,
  "consumer_found": true
}

Consumer Not Found:

{
  "success": true,
  "consumer_found": false
}

Opt-Out Request

Purpose: Process a consumer's request to opt out of targeted data sale/sharing.

Expected Actions:

1. Use email to find corresponding consumer records in your downstream systems
2. Set opt-out flags in your systems or suppress the consumer from future data sharing/sale
3. Return a successful response

Example Response:

{
  "success": true,
  "outcome": "confirmed",
  "consumer_found": true,
  "message": "Consumer opted out successfully."
}

Asynchronous Processing:

{
  "success": true,
  "outcome": "submitted",
  "consumer_found": true,
  "message": "Opt-out request queued for processing."
}

Delete Request

Purpose: Process a consumer's request to delete their personal data from your systems.

Expected Actions:

1. Use email to find corresponding consumer records in your downstream systems
2. Delete or anonymize personal data
3. Return a successful response

Example Response:

{
  "success": true,
  "outcome": "confirmed",
  "consumer_found": true,
  "message": "Consumer data deleted successfully."
}

Error Handling

Idempotency

Use tracker_id to ensure idempotent processing. If you receive a duplicate request (same tracker_id), you should:

• Return the same response as the original
• Do not re-process the request (or process it in an idempotent way)

Polaris strives to only send one request per tracker_id, but network issues may cause retries.

Error Response Format (HTTP 500)

If processing fails, return an HTTP 500 status with details:

{
  "success": false,
  "outcome": "failed",
  "consumer_found": false,
  "message": "Database connection timeout"
}

Security Best Practices

1. Validate the Authorization token on every request
2. Use HTTPS for all API endpoints

Processing Guidelines

Synchronous vs Asynchronous Processing

You can choose to process requests synchronously or asynchronously:

• Synchronous (outcome: confirmed): Process the request immediately and confirm completion before responding. Use this for operations that complete quickly (under 30 seconds).

• Asynchronous (outcome: submitted): Accept the request and queue it for later processing. Use this for operations that may take longer than 30 seconds or involve multiple systems. In Polaris, this will be reflected as "Request automatically sent" in the workflow and considered a successful automation outcome.

Response Time Requirements

• Lookup requests: Respond within 30 seconds with whether the consumer was found
• Opt-Out and Delete requests: Respond within 30 seconds, either confirming immediate completion or accepting for later processing

Testing Your Integration

Before going live, test your custom API endpoints with sample requests:

1. Verify authentication is working correctly
2. Test each pathway (lookup, opt-out, delete) with sample consumer data
3. Test error scenarios (invalid tokens, timeouts, missing data)
4. Verify idempotency with duplicate tracker_id values
5. Check that responses match the expected format

Next Steps

Once your custom API endpoints are implemented and tested in your downstream systems:

1. Set up your Custom API Endpoints integration in Polaris, providing your host URL, path prefix, and Bearer token
2. Toggle on the automations you want to enable (lookup, opt-out, delete)
3. Test the integration by submitting privacy requests in Polaris