canonical: https://jentic.com/apis/restrata.net/restrata-location-ingestion

# Restrata Static Location Connector - Location Ingestion API

The Restrata Static Location Connector API loads static locations, such as offices and home addresses, into a Restrata tenant in bulk. A single synchronous call takes an array of location records, validates each one, and publishes the valid batch to NATS JetStream for asynchronous processing. It answers straight away with 200 OK, or with a 422 that maps each failing location id to its validation errors, so the caller knows exactly which records to fix.

## For AI agents

Push a batch of Work or Home location records, with address lines and coordinates, into one Restrata tenant and get per-location validation errors back.

## Scope

Does not handle person profiles, travel bookings, risk alerts, or reading locations back out of Restrata. Use for bulk loading static locations into a Restrata tenant only.

## Capabilities

- Load a batch of static locations into one Restrata tenant with POST /{tenantId}/sync-locations
- Tag each location as Work or Home with the type field and mark one as isPrimary
- Send address lines, city, region, country, and postCode alongside latitude and longitude for each location
- Read the 422 response's map of location id to validation errors and resubmit only the records that failed

## Use cases

### Agent-run location sync through Jentic

An operations agent connected through Jentic searches by intent for syncing locations into Restrata, gets the sync-locations operation with its input schema, and posts the current list of company sites for one tenant. The Restrata key stays in your own Jentic One instance, and the agent reports the 200 or the per-location 422 errors back to you.

Example prompt: POST /{tenantId}/sync-locations for tenant 'acme' with locations [{id: 'dub-hq', type: 'Work', name: 'Dublin HQ', city: 'Dublin', country: 'IE', latitude: 53.34, longitude: -6.26, isPrimary: true}]

### Facilities register to Restrata pipeline

When a facilities register or property system changes, a pipeline maps each site to a Restrata location record with id, type Work, address lines, postCode, and coordinates, then sends the whole batch in one call. Because the endpoint validates synchronously and publishes to NATS JetStream for async processing, the pipeline learns about bad records immediately without waiting for downstream processing.

Example prompt: Read the changed sites from the facilities export, build a locations array with id, type 'Work', line1, city, country, and postCode for each, and POST it to /{tenantId}/sync-locations

### Validation error triage

If a batch returns 422, the error object maps each failing location id to its list of validation problems, such as a non-Work location missing its title or line1. An agent can group those errors, fix or flag the source records, and resubmit only the corrected locations.

Example prompt: After a 422 from POST /{tenantId}/sync-locations, list each location id in the error map with its messages, fill the missing title and line1 for Home locations, and resubmit those records

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/{tenantId}/sync-locations` | Sync a batch of static locations |

## Key resources

- **Static location** — A Work or Home location with address lines, postCode, country, and latitude and longitude, keyed by its own id

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 63 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 74 / 100
  - AI-Readiness & Agent Experience: 46 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/restrata.net/restrata-location-ingestion/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Restrata location connector by hand means holding a per-tenant X-API-Key, choosing the right regional host, and shaping the locations array to its validation rules. Through Jentic you install once, import the API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Restrata puts the tenant id in the URL path (/{tenantId}/sync-locations), so a rule can pin your agent to one tenant: it can load locations for that tenant and nothing else.
- **Credential handling:** Your Restrata API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'sync office locations into Restrata', and Jentic returns the matching Restrata operation with its input schema so the agent sends the right fields without browsing the reference docs.

## Related APIs

- **Restrata People Connector - Person Profile Ingestion API** — Bulk-loads person profiles into the same Restrata tenant
- **Smarty US Autocomplete API** — US address autocomplete and standardisation
- **Postio API** — UK address lookup by postcode or UDPRN

## FAQ

### What authentication does the Restrata Location Ingestion API use?

Per its OpenAPI spec, the API takes an API key in the X-API-Key header, and Restrata generates a random key per tenant and endpoint. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### What does the Restrata location sync return when a record is invalid?

POST /{tenantId}/sync-locations validates every location in the batch. If any fail, it returns 422 with an error object that maps each location id to its list of validation errors. A location whose type is not Work needs title and line1, and every location needs id and type.

### What are the rate limits for the Restrata Location Ingestion API?

The OpenAPI spec does not specify rate limits or a maximum batch size. Ask Restrata Platform Engineering, the contact listed in the spec at platform@restrata.com, for current limits before sending very large batches.

### Is there a Restrata MCP server?

You don't need an MCP server to give your agent the Restrata Location Ingestion API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. Operations are found by intent when needed, so no extra tool definitions sit in your agent's context.

### How do I sync locations into Restrata through Jentic?

Install Jentic One, add the Restrata Location Ingestion API from the directory, and store the X-API-Key Restrata issued for your tenant. Your agent searches for 'sync static locations into Restrata', gets POST /{tenantId}/sync-locations with its schema, and posts the locations array. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Restrata Location Ingestion API?

Yes. Write a rule that allows POST `/acme/sync-locations` only, so the agent can load locations into the acme tenant but cannot write to any other tenant id, and every call it makes is logged.
