API Endpoint Integration for Connected Systems

info

This is a paid add-on, contact your Customer Success representative to enable the TrueVault Connected System functionality.

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, access, 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 four automation pathways:

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

note

The Access endpoint acknowledges the request; it does not return the consumer's personal data to Polaris. You must still complete the request through your existing access request process — compiling the data package and delivering it to the consumer, for example by emailing it to them. See Access Request for details.

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)
• Bearer Token: A secure token that Polaris will include in the Authorization header

Each automation (Lookup, Access, Opt-Out, and Delete) sends its request to a path appended to the Host URL. Each path is optional and defaults to /lookup, /access, /opt-out, and /delete; you can override it in that workflow's settings — for example, to add a shared prefix such as /privacy/lookup.

The full endpoint URL is constructed as: {host}{path}

For example, using the default paths:

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

Or, overriding the Lookup path with /privacy/lookup:

• Lookup: https://api.example.com/privacy/lookup

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 | access | 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, access, 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 access, 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 access/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 access, opt-out, or 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
}

Access Request

Purpose: Process a consumer's request to know what personal data you hold about them.

caution

Do not return the consumer's personal data in the response body. This endpoint acknowledges the request only — Polaris does not ingest, store, or forward a data package returned here. You must still deliver the compiled data to the consumer yourself through your existing access request process, for example by emailing it to them.

Expected Actions:

1. Use email to find corresponding consumer records in your downstream systems
2. Compile the consumer's personal data, then you MUST complete the request by notifying the consumer and delivering the data you found to them, for example by email
3. Return a successful response

Because compiling a data package rarely finishes within the 30-second response window, most implementations queue the work and return submitted.

Example Response - Queued for Processing:

{
  "success": true,
  "outcome": "submitted",
  "consumer_found": true,
  "message": "Access request queued for data package assembly."
}

Immediate Completion:

{
  "success": true,
  "outcome": "confirmed",
  "consumer_found": true,
  "message": "Consumer data package sent."
}

Consumer Not Found:

{
  "success": true,
  "outcome": "no_data",
  "consumer_found": false,
  "message": "No matching consumer records."
}

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
• Access, 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, access, 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 and Bearer token
2. Toggle on the automations you want to enable (lookup, access, opt-out, delete), overriding the default /lookup, /access, /opt-out, and /delete paths if needed
3. Test the integration by submitting privacy requests in Polaris