# API Reference

The SecurePoint v1 API: sanctions screening, ownership checks, evidence, adjudication, visitor check-in and continuous monitoring. The full contract is the OpenAPI 3.0 specification at [/api/docs/openapi](/api/docs/openapi); this page is the quickstart.

## Base URL

`https://app.securepointusa.com/api`

The same URL serves production and sandbox organizations. Your key decides which one you are working in.

## Authentication

Send your API key as a bearer token:

```
Authorization: Bearer spusa_...
```

- Keys are issued per organization by SecurePoint. Every request acts in the key's organization, which is taken from the key on the server, never from the request.
- Keys carry scopes. `customer_api` covers every v1 route your organization is entitled to; narrower keys name scopes such as `screening`, `adjudication`, `monitoring:read`, `monitoring:write`, `monitoring:adjudicate` and `monitoring:imports`.
- Keys expire (90 days by default). An expired key gets 401; ask for a rotated key.
- A key may have a monthly quota. When it is used up, every call answers 429 `QUOTA_EXCEEDED` until the next month.
- `/v1/audit/integrity` and `/v1/compliance/reports` accept a signed-in user's session only, not an API key.

## First call

```
curl https://app.securepointusa.com/api/v1/whoami \
  -H "Authorization: Bearer $SPUSA_API_KEY"
```

The response names your organization, `environment` (`sandbox` or `production`), the key's scopes, expiry and quota, and which products your organization can reach (`access`). It does not count toward your quota.

## Sandbox

A sandbox is a separate test organization that SecurePoint sets up for you, with its own key. It runs the same code, the same screening engine and the same sanctions lists as production at the same URL; only its data is separate. Screening results there are real results against current lists, so use subjects you expect to match or clear. Check `GET /api/v1/whoami` returns `environment: "sandbox"` before you send test traffic. Ask your SecurePoint contact for one.

## Responses and errors

Every response is JSON in one envelope:

```
{ "success": true, "data": { ... }, "meta": { "requestId": "..." } }
{ "success": false, "error": { "code": "...", "message": "...", "details": { ... } }, "meta": { "requestId": "..." } }
```

Quote `meta.requestId` when you contact support.

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `INVALID_INPUT` | The body or parameters failed validation; `details.issues` lists them |
| 401 | `UNAUTHORIZED` | Missing, invalid, expired or revoked credentials |
| 402 | `ENTITLEMENT_REQUIRED` | Your organization's plan does not include this product |
| 403 | `FORBIDDEN` / `FEATURE_DISABLED` | The key lacks the scope, the organization is not active, or the feature is off for it |
| 404 | `NOT_FOUND` | No such record in your organization |
| 429 | `RATE_LIMITED` / `QUOTA_EXCEEDED` | Slow down (`details.retry_after_ms`), or the monthly quota is used up |
| 500 | `INTERNAL_ERROR` | Retry with backoff; contact support with the requestId if it persists |

Responses on most routes carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.

## Webhooks

Outbound event webhooks are not generally available. Poll `GET /api/v1/screenings/{id}` and `GET /api/v1/adjudication/queue` for results and decisions.

## Endpoints

### Account
- `GET /api/v1/whoami`: which organization and environment the key acts in, its quota and access

### Screening
- `POST /api/v1/prescreen`: screen a person or organization against sanctions and restricted-party lists
- `GET /api/v1/screenings/{id}`: fetch a screening result
- `GET /api/v1/screenings/{id}/evidence`: download the evidence PDF for a screening (Evidence and Adjudication add-on)
- `POST /api/v1/ownership/check`: OFAC 50 percent ownership check through the ownership graph (Ownership add-on). This checks ownership only; use prescreen to screen the entity itself.
- `POST /api/v1/vendors/screen`: screen a vendor

### Adjudication (Evidence and Adjudication add-on)
- `GET /api/v1/adjudication/queue`: list cases waiting for a decision
- `GET /api/v1/adjudication/{id}`: fetch one case
- `POST /api/v1/adjudication/{id}/disposition`: record CLEARED, ESCALATED or DENIED. With an API key, name the person who decided (`reviewer.id`, `reviewer.display_name`).
- `PUT /api/v1/adjudication/rules`: manage adjudication rules

### Visitors
- `POST /api/v1/checkin`: check in a visitor
- `POST /api/v1/sessions/{id}/update`: update a visitor session

### Audit and compliance
- `GET /api/v1/audit/export`: export your organization's audit log
- `GET /api/v1/audit/integrity`: verify your organization's audit log hash chain (signed-in users)
- `GET /api/v1/compliance/reports`: compliance summary for a period (signed-in users)

### Continuous monitoring (when Continuous Monitoring is enabled for your organization)
- `GET /api/v1/monitoring/subjects`: list monitored subjects
- `POST /api/v1/monitoring/subjects/sync`: add, update or deactivate monitored subjects
- `GET /api/v1/monitoring/runs`: list monitoring runs
- `GET /api/v1/monitoring/runs/{id}`: one run and its items
- `GET /api/v1/monitoring/hits`: list hits
- `GET /api/v1/monitoring/hits/{id}`: one hit
- `POST /api/v1/monitoring/hits/{id}/adjudicate`: record a decision on a hit
- `POST /api/v1/monitoring/imports/preview`: preview a subject import
- `POST /api/v1/monitoring/imports/{id}/commit`: commit a previewed import
