Integration API

The Integration API lets your own software work with Neostra without a user signing in. A CRM can file a privacy rights request on behalf of a customer, a service desk can check where a request stands, and an automation platform can keep its records in step with Neostra. Every call is authenticated with a tenant API token that carries only the scopes you grant it.

The API is organised by module. Each module exposes its own set of endpoints and scopes under a common base path, authentication scheme, and response format, which are described first on this page. Endpoints for further modules are added over time under the same conventions.

Getting started

Base URL and versioning

All endpoints live under /api/integration/v1 on the host you use to sign in to Neostra. The examples on this page use https://<your-neostra-host> as a placeholder.

The path carries the API version. Within a version, new fields may be added to responses; your client should ignore fields it does not recognise.

Create an API token

API tokens are tenant-level credentials that represent your systems rather than a person.

The API Tokens page lists each token's name, a masked value, scopes, status, last used time, and expiry. Revoking a token takes effect immediately and cannot be undone.

Authentication

Send the token as a bearer token in the Authorization header on every request.

Authorization: Bearer neo_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Token secrets begin with neo_sk_ followed by an environment label and a random component. Treat the entire string as the secret.

Scopes

A scope grants access to a specific capability within a module. A token may hold any combination of scopes. Holding the scope is sufficient to call the endpoint; no additional user permission applies.

Response format

Every response uses the same envelope. On success, success is true and the payload is in data. On failure, success is false and errors lists one or more messages; validation errors name the offending field.

{
  "success": false,
  "message": "Error",
  "errors": [
    { "field": "requestTypes", "message": "List must not be empty" }
  ]
}

Limits and behaviour

• Idempotency: requests are not deduplicated by the API. Each successful create call produces a new record. If your client retries after a timeout, check the record's status first or deduplicate on your side.
• Rate limits: no per-token rate limit is enforced today. Keep call volumes reasonable and poll for status no more often than your use case requires.
• Subscription limits: records created through the API count towards the same allowances as records created in the application.
• Auditing: every action performed with a token is recorded in the audit trail under the token's name.

Endpoints by module

curl -X POST "https://<your-neostra-host>/api/integration/v1/subject-request" \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "intakeFormId": "<intake-form-id>",
    "requestTypes": ["<request-type-identifier>"],
    "locale": "en",
    "email": "data.subject@example.com",
    "userEnteredData": [
      { "key": "Email", "value": "data.subject@example.com" },
      { "key": "First Name", "value": "Asha" },
      { "key": "Last Name", "value": "Rao" }
    ],
    "userInfo": {
      "email": "data.subject@example.com",
      "firstName": "Asha",
      "lastName": "Rao",
      "phone": { "countryCode": "+91", "phoneNumber": "9000000000" },
      "country": "IN",
      "state": "KA"
    }
  }'

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "66c0a1f2e4b0a1b2c3d4e5f6",
    "status": "INITIATED",
    "requestVerified": false,
    "requestTypes": ["<request-type-identifier>"],
    "createdAt": "2026-06-18T09:41:12.318Z"
  }
}

curl "https://<your-neostra-host>/api/integration/v1/subject-request/<request-id>" \
  -H "Authorization: Bearer <your-api-token>"

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "66c0a1f2e4b0a1b2c3d4e5f6",
    "status": "ACTIVE",
    "requestVerified": true,
    "requestTypes": ["<request-type-identifier>"],
    "createdAt": "2026-06-18T09:41:12.318Z"
  }
}