> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch Org Settings
> Queues a live sync of your organization's settings from the connected EMR system.
Cobalt automatically syncs org settings **nightly for every organization**. You
do **not** need to call this endpoint on a schedule — the nightly sync already
keeps providers, locations, visit types, and the rest of your org settings up to
date. Use this endpoint sparingly, only when you need a refresh sooner than the
next nightly run (for example, right after adding a new provider or location in
your EMR and wanting it reflected immediately).
This is an asynchronous operation. It returns immediately with a
`job_execution_id` and delivers an `org_settings.synced` webhook when the sync
finishes. To read the synced values, use the corresponding read endpoints such as
[Get Providers](/api-reference/providers/get),
[Get Locations](/api-reference/locations/get),
[Get Visit Types](/api-reference/visit-types/get),
[Get Visit Statuses](/api-reference/visit-statuses/get), and
[Get Settings](/api-reference/settings/get).
## What Gets Synced
A single sync refreshes the full set of organization settings from the EMR:
* Providers
* Locations
* Visit types
* Visit statuses
* Insurance companies
* Pharmacies
* Referring providers
* Timezone
* Required patient fields
## Concurrency
Only one org settings sync can be in flight per linked account at a time. If a sync
is already running when you call this endpoint, the request returns `409` with the
`job_execution_id` of the in-flight sync so you can wait for it to finish rather
than queuing a duplicate.
## Example Request
```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/org-settings/fetch \
-H "Content-Type: application/json" \
-H "client_id: your_client_id" \
-H "client_secret: your_client_secret" \
-H "access_token: your_access_token" \
-d '{}'
```
### Routing the completion webhook
The completion webhook is delivered to your account's registered webhook URLs by
default. To route this specific sync's `org_settings.synced` event elsewhere,
include a `callback_urls` array (see [Webhook setup](/docs/webhooks/setup)). Each
URL must use HTTPS.
```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/org-settings/fetch \
-H "Content-Type: application/json" \
-H "client_id: your_client_id" \
-H "client_secret: your_client_secret" \
-H "access_token: your_access_token" \
-d '{
"callback_urls": ["https://your-domain.com/cobalt-webhook"]
}'
```
### Example Response
```json theme={null}
{
"success": true,
"status": "queued",
"message": "Org settings sync started. An org_settings.synced webhook will be sent when it completes.",
"job_execution_id": "job_1J9X2q2eZvKYlo2Cmnopqr"
}
```
## Webhook Notification
When the sync completes, Cobalt sends an `org_settings.synced` webhook to your
registered endpoint (or to `callback_urls` if you supplied them). The payload is
intentionally minimal — it signals completion and reports counts of what changed.
Re-fetch the synced values from the read endpoints listed above.
```json theme={null}
{
"id": "508c368e7de13b40f9397eec966d0329",
"access_token_reference_id": "your-reference-id",
"object": "event",
"job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
"created": "2026-07-22T08:50:42.491-07:00",
"type": "org_settings.synced",
"action": "ehr_sync",
"data": {
"status": "completed",
"summary": {
"providers_created": 1,
"providers_updated": 3,
"locations_created": 0,
"locations_updated": 2,
"visit_types_created": 0,
"visit_types_updated": 5,
"visit_statuses_created": 0,
"visit_statuses_updated": 0,
"insurance_companies_created": 0,
"pharmacies_created": 0,
"pharmacies_updated": 0,
"referring_providers_created": 0,
"referring_providers_updated": 1,
"policy_types_count": 12,
"staff_list_count": 24,
"required_patient_fields_synced": true,
"timezone_synced": true,
"link_org_updated": true
}
}
}
```
You must be subscribed to the `org_settings.synced` event for the webhook to be
delivered. See [Webhook setup](/docs/webhooks/setup) to manage your
subscriptions.
## OpenAPI
````yaml POST /org-settings/fetch
openapi: 3.0.0
info:
title: Cobalt API
version: 1.0.1
description: API for interacting with Cobalt's EHR integration services
servers:
- url: https://api.usecobalt.com/v1
security:
- ClientCredentials: []
ClientSecret: []
AccessToken: []
paths:
/org-settings/fetch:
post:
summary: Fetch Org Settings
description: >-
Queues a live sync of your organization's settings (providers,
locations, visit types, visit statuses, insurance companies, pharmacies,
referring providers, timezone, and required patient fields) from the
connected EMR system. This is an asynchronous operation that returns
immediately with a job identifier and delivers an `org_settings.synced`
webhook on completion. Cobalt already syncs org settings nightly for
every organization, so this endpoint is only needed when you require a
refresh sooner than the next nightly run; it does not need to be called
on a schedule.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
callback_urls:
type: array
items:
type: string
format: uri
description: >-
Optional. One or more HTTPS URLs to receive the
`org_settings.synced` completion webhook for this request
instead of your account's registered webhook URLs. Accepts a
single string or an array of strings. Each URL must use
HTTPS.
responses:
'202':
description: Sync accepted and queued for processing
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
status:
type: string
example: queued
message:
type: string
example: >-
Org settings sync started. An org_settings.synced webhook
will be sent when it completes.
job_execution_id:
type: string
description: Identifier for the queued sync job.
'400':
description: Bad request (for example, invalid `callback_urls`)
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: >-
callback_urls must contain only non-empty https URL
strings.
'409':
description: An org settings sync is already in progress for this account
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
status:
type: string
example: running
message:
type: string
example: >-
An org settings sync is already in progress for this
account. Please try again once it completes.
job_execution_id:
type: string
description: Identifier of the sync job that is already in flight.
components:
securitySchemes:
ClientCredentials:
type: apiKey
in: header
name: client_id
ClientSecret:
type: apiKey
in: header
name: client_secret
AccessToken:
type: apiKey
in: header
name: access_token
````