> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiomancer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Seven endpoints for CRM integrations, webhook connectors, and API key management in Locus — wire location intelligence into Salesforce and HubSpot.

Push enriched Locus intelligence into your CRM, ticketing system, or automation platform. Each integration enriches records with composite scores, safety levels, permit activity, and neighborhood context.

All integration endpoints share the same lifecycle:

1. **Connect** — `POST` with credentials to verify and save the integration.
2. **Check status** — `GET` to see whether the integration is active.
3. **Disconnect** — `DELETE` to deactivate.

You can optionally include an `enrich` object in the `POST` body to trigger immediate enrichment of a specific record.

***

## `POST` `/api/v1/integrations/salesforce`

<Note>Requires Bearer token.</Note>

Push enriched location data to Salesforce CRM.

**Request body**

```json theme={null}
{
  "instance_url": "https://yourorg.my.salesforce.com",
  "access_token": "00D...",
  "refresh_token": "5Aep...",
  "object_type": "Lead",
  "enrich": {
    "record_id": "00Q5f00000XXXXX",
    "address": "123 Market St, San Francisco, CA"
  }
}
```

| Field           | Type   | Required | Description                                                    |
| --------------- | ------ | -------- | -------------------------------------------------------------- |
| `instance_url`  | string | ✓        | Salesforce instance URL (`*.salesforce.com` or `*.force.com`). |
| `access_token`  | string | ✓        | OAuth access token.                                            |
| `refresh_token` | string | ✓        | OAuth refresh token.                                           |
| `object_type`   | string | ✓        | Target object: `Lead`, `Account`, `Opportunity`, or `Custom`.  |
| `enrich`        | object |          | Optional. Enrich a record immediately on setup.                |

**Enrichment fields pushed to Salesforce:**

| Salesforce field           | Description                           |
| -------------------------- | ------------------------------------- |
| `Axiom_Score__c`           | Composite score (0–100).              |
| `Axiom_Safety_Level__c`    | Safety assessment level.              |
| `Axiom_Permit_Momentum__c` | Permit activity momentum indicator.   |
| `Axiom_Fragility_Score__c` | Supply chain fragility score.         |
| `Axiom_Profile__c`         | Scoring profile used.                 |
| `Axiom_Permits_12m__c`     | Permit count over the last 12 months. |
| `Axiom_Neighborhood__c`    | Resolved neighborhood name.           |
| `Axiom_Enriched_At__c`     | Timestamp of last enrichment.         |

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/v1/integrations/salesforce" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "instance_url": "https://yourorg.my.salesforce.com",
    "access_token": "00D...",
    "refresh_token": "5Aep...",
    "object_type": "Lead"
  }'
```

***

## `POST` `/api/v1/integrations/hubspot`

<Note>Requires Bearer token.</Note>

Push enriched data to HubSpot CRM contacts, companies, or deals.

**Request body**

```json theme={null}
{
  "access_token": "pat-na1-...",
  "object_type": "contacts",
  "enrich": {
    "record_id": "123456",
    "address": "456 Broadway, New York, NY"
  }
}
```

| Field           | Type   | Required | Description                                                                            |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `access_token`  | string | ✓        | OAuth token or private app token.                                                      |
| `refresh_token` | string |          | Required for OAuth flows. Omit for private app tokens.                                 |
| `object_type`   | string | ✓        | Target object: `contacts`, `companies`, or `deals`.                                    |
| `enrich`        | object |          | Optional. Enrich a record immediately. Include `record_id` and `address` or `company`. |

**Enrichment properties pushed to HubSpot:**

`axiom_score`, `axiom_safety`, `axiom_permit_activity`, `axiom_fragility`, `axiom_profile`, `axiom_permits_12m`, `axiom_neighborhood`, `axiom_enriched_at`

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/v1/integrations/hubspot" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "access_token": "pat-na1-abc123",
    "object_type": "companies"
  }'
```

***

## `POST` `/api/v1/integrations/dynamics`

<Note>Requires Bearer token.</Note>

Push enriched data to Microsoft Dynamics 365 entities via the Dataverse Web API.

**Request body**

```json theme={null}
{
  "tenant_id": "your-azure-tenant-id",
  "client_id": "your-app-registration-id",
  "client_secret": "your-client-secret",
  "resource_url": "https://yourorg.crm.dynamics.com",
  "entity_type": "lead"
}
```

| Field           | Type   | Required | Description                                                                            |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `tenant_id`     | string | ✓        | Azure AD tenant ID.                                                                    |
| `client_id`     | string | ✓        | App registration client ID.                                                            |
| `client_secret` | string | ✓        | App registration client secret.                                                        |
| `resource_url`  | string | ✓        | Dynamics instance URL (must end in `.dynamics.com` or `.crm.dynamics.com`).            |
| `entity_type`   | string | ✓        | Dynamics entity logical name (e.g. `lead`, `account`, `opportunity`).                  |
| `enrich`        | object |          | Optional. Enrich a record immediately. Include `record_id` and `address` or `company`. |

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/v1/integrations/dynamics" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "tenant_id": "abc-123",
    "client_id": "def-456",
    "client_secret": "secret",
    "resource_url": "https://yourorg.crm.dynamics.com",
    "entity_type": "lead"
  }'
```

***

## `POST` `/api/v1/integrations/zoho`

<Note>Requires Bearer token.</Note>

Push enriched data to Zoho CRM modules.

**Request body**

```json theme={null}
{
  "access_token": "1000.abc123...",
  "refresh_token": "1000.def456...",
  "module": "Leads",
  "enrich": {
    "record_id": "5234876000001234567",
    "address": "789 Pine St, Denver, CO"
  }
}
```

| Field           | Type   | Required | Description                                                                                     |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `access_token`  | string | ✓        | Zoho OAuth access token.                                                                        |
| `refresh_token` | string | ✓        | Zoho OAuth refresh token.                                                                       |
| `api_domain`    | string |          | API domain. Defaults to `https://www.zohoapis.com`. Also accepts `.zoho.com` or `.zohoapis.eu`. |
| `module`        | string |          | Target module: `Leads`, `Accounts`, `Contacts`, or `Deals`. Defaults to `Leads`.                |
| `enrich`        | object |          | Optional. Enrich a record immediately. Include `record_id` and `address` or `company`.          |

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/v1/integrations/zoho" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "access_token": "1000.abc123...",
    "refresh_token": "1000.def456...",
    "module": "Accounts"
  }'
```

***

## `POST` `/api/v1/integrations/zendesk`

<Note>Requires Bearer token.</Note>

Enrich Zendesk tickets with location intelligence. Adds an internal note with scoring data and sets custom ticket fields.

**Request body**

```json theme={null}
{
  "subdomain": "mycompany",
  "api_token": "your-zendesk-api-token",
  "email": "admin@mycompany.com",
  "enrich": {
    "ticket_id": "12345",
    "address": "100 Oak Ave, Austin, TX"
  }
}
```

| Field       | Type   | Required | Description                                                                             |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `subdomain` | string | ✓        | Your Zendesk subdomain (e.g. `mycompany` for `mycompany.zendesk.com`).                  |
| `api_token` | string | ✓        | Zendesk API token.                                                                      |
| `email`     | string | ✓        | Admin email address for authentication.                                                 |
| `enrich`    | object |          | Optional. Enrich a ticket immediately. Include `ticket_id` and `address` or `facility`. |

**Enrichment behavior:**

* Adds a **private internal note** on the ticket with composite score, safety level, and neighborhood data.
* Sets custom ticket fields: `axiom_score` and `axiom_safety`.

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/v1/integrations/zendesk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "subdomain": "mycompany",
    "api_token": "abc123",
    "email": "admin@mycompany.com"
  }'
```

***

## `POST` `/api/v1/integrations/zapier`

<Note>Requires Bearer token.</Note>

Forward Locus events to any webhook URL. Works with Zapier, Make, n8n, or any platform that accepts webhooks.

**Request body**

```json theme={null}
{
  "webhook_url": "https://hooks.zapier.com/hooks/catch/123/abc/",
  "trigger_events": ["score_change", "permit_surge", "fragility_spike"],
  "name": "My Zapier Zap"
}
```

| Field            | Type   | Required | Description                                                                                    |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `webhook_url`    | string | ✓        | HTTPS webhook URL to receive events.                                                           |
| `trigger_events` | array  |          | Event types to forward. Defaults to all.                                                       |
| `format`         | string |          | Payload format: `json` (default) or `form` (form-urlencoded).                                  |
| `name`           | string |          | Friendly name. Defaults to `Zapier Webhook`.                                                   |
| `enrich`         | object |          | Optional. Push an enrichment payload immediately. Include `address`, `company`, or `facility`. |

**Available trigger events:**

| Event              | Description                                        |
| ------------------ | -------------------------------------------------- |
| `hotspot_detected` | A new permit or activity hotspot appears.          |
| `fragility_spike`  | Supply chain fragility score spikes for a company. |
| `rule_change`      | Zoning or regulatory rule change detected.         |
| `permit_surge`     | Permit filing rate exceeds normal levels.          |
| `score_change`     | Composite score changes significantly.             |
| `shortage_alert`   | Drug shortage or supply disruption detected.       |

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/v1/integrations/zapier" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "webhook_url": "https://hooks.zapier.com/hooks/catch/123/abc/",
    "trigger_events": ["permit_surge", "score_change"]
  }'
```

***

## Managing integrations

All integration endpoints support `GET` and `DELETE` methods for status checks and deactivation.

### Check status

```bash theme={null}
curl "https://axiomlocus.io/api/v1/integrations/hubspot" \
  -H "Authorization: Bearer al_your_key_here"
```

```json theme={null}
{
  "configured": true,
  "object_type": "contacts",
  "active": true,
  "last_sync_at": "2026-04-19T10:30:00Z"
}
```

### Deactivate

```bash theme={null}
curl -X DELETE "https://axiomlocus.io/api/v1/integrations/hubspot" \
  -H "Authorization: Bearer al_your_key_here"
```

***

## `POST` `/api/v1/keys`

<Note>Requires Bearer token.</Note>

Create and manage API keys programmatically. Keys are prefixed with `al_` and can be scoped to specific endpoints.

**Request body**

```json theme={null}
{
  "action": "create",
  "name": "Production Key",
  "scopes": ["score", "enrich", "permits"]
}
```

| Field    | Type   | Required | Default | Description                                      |
| -------- | ------ | -------- | ------- | ------------------------------------------------ |
| `action` | string | ✓        |         | Action: `create`, `list`, or `revoke`.           |
| `name`   | string |          |         | Human-readable key name (required for `create`). |
| `scopes` | array  |          |         | Endpoint scopes. Omit for full access.           |
| `key_id` | string |          |         | Key ID to revoke (required for `revoke` action). |

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/v1/keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{"action":"create","name":"Production Key","scopes":["score","enrich"]}'
```

**Response**

```json theme={null}
{
  "key": {
    "id": "key_abc123",
    "name": "Production Key",
    "token": "al_live_abc123def456ghi789",
    "scopes": ["score", "enrich"],
    "created_at": "2026-03-31T12:00:00Z"
  }
}
```

| Field        | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| `key.id`     | string | Key identifier for management operations.   |
| `key.token`  | string | Full API key (only shown once on creation). |
| `key.scopes` | array  | Endpoint scopes this key can access.        |