---
name: upload-provider-csv
description: Upload a CSV of dental practice, location and provider data to Intelibly with the Partner CSV Upload API (OAuth 2.0 client credentials). Use when an Intelibly partner needs to send, list, download or delete partner CSV files, or build a CSV in Intelibly's template format.
---

# Upload provider data to Intelibly (Partner CSV Upload API)

Source documentation (public):
- Partner CSV Upload API: https://developer.intelibly.com/partner-api/csv-upload-api.md
- CSV Template Field Reference: https://developer.intelibly.com/partner-api/csv-template.md

Base URL (production): `https://app.intelibly.com`. A staging/dev base URL is provided separately by Intelibly.
Uploads are associated automatically with the partner organization that owns the API credentials.

## Credentials and security

- Intelibly issues each partner a `client_id` and `client_secret`. For credentials or questions about the CSV format, contact your Intelibly Provider Relations representative. You cannot self-register.
- Never embed `client_secret` or access tokens in prompts, code you share, client-side apps or public repositories. Read them from environment variables or a secrets manager.
- Use HTTPS only. Use tokens only for server-to-server automation. Rotate credentials if compromised.
- Download URLs are short-lived; treat them as sensitive while valid.

## Steps

### 1. Get an access token

```
POST https://app.intelibly.com/api/token
Content-Type: application/json

{"client_id": "$INTELIBLY_CLIENT_ID", "client_secret": "$INTELIBLY_CLIENT_SECRET", "grant_type": "client_credentials"}
```

`200 OK` returns `{"access_token": "...", "token_type": "Bearer", "expires_in": 3600}`. Errors: `400` with `{"error": "invalid_client"}` or `{"error": "invalid_request"}`.
Send `Authorization: Bearer <access_token>` on every request below. Tokens last about 1 hour; request a new one when `expires_in` elapses and do not reuse expired tokens.

### 2. (Optional) Get the CSV header template

`GET https://app.intelibly.com/api/csv_uploads/template` returns `text/csv` (`partner_import.csv`) containing only the recommended header row. Use it as the header of your file.

### 3. Build the CSV

Header row documented on the upload page (case-insensitive):

```
practice_name,practice_email,practice_website,practice_contact_name,location_name,location_phone,location_street,location_city,location_state,location_zip,location_internal_id,provider_name,provider_specialty,provider_internal_id,partner_tier_name,partners_internal_id,npi_number,partner_tags
```

Example row (fictional data):

```
Sample Family Dental,frontdesk@example.com,www.example.com,Jordan Sample,Main Office,(210) 555-0123,100 Example St.,San Antonio,TX,78229,,Dr. Jordan Sample,General Dentist,,gold,,1234567893,
```

Field requirements (from the CSV Template Field Reference):
- Required for all implementations: `practice_name`, `practice_email` (practice owner's email; used to create the Intelibly account and dashboard access), `practice_contact_name` (practice owner's full name), `location_phone`, `location_street` (include suite), `location_city`, `location_state`, `location_zip`, `provider_name`, `provider_specialty`.
- FinderCONNECT Button: `location_internal_id` and `provider_internal_id` (stable, globally unique partner IDs that also appear on the partner's provider finder page) are required. If those are not available, `provider_location_internal_id` (the partner's directory-point ID for the provider-location pairing) is required.
- FinderCONNECT Map only (optional): `partner_tier_name` (ranks providers in search results) and `partner_tags` (groups locations; comma-separated inside one quoted cell).
- Optional: `practice_website`, `location_name`, `practice_internal_id`, `npi_number`, `partners_internal_id`.
- `provider_specialty` should be one of: Endodontist, General Dentist, Oral Surgeon, Orthodontist, Other, Pediatric Dentist, Periodontist, Prosthodontist. Unmatched or blank values default to General Dentist.
- The two doc pages differ slightly (the upload page marks `provider_specialty` optional and does not list `provider_location_internal_id` or `practice_internal_id`). Your Intelibly contact confirms which internal IDs your integration requires.

### 4. Upload the file

```
curl -X POST "https://app.intelibly.com/api/csv_uploads" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@./practices.csv"
```

Constraints: `multipart/form-data` with one field `file`; `.csv` extension only; `text/csv`; maximum 200 MB (209,715,200 bytes); 1 file per request.
`201 Created` returns `data` with `id` (UUID), `filename`, `file_size`, `content_type`, `inserted_at`. Keep the `id`.
Errors: `400`/`422` for a missing file, non-.csv filename, empty file or file too large (field errors such as `{"errors": {"filename": ["must be a CSV file"]}}`); `401` for a missing or invalid token.

### 5. Confirm the upload

`GET https://app.intelibly.com/api/csv_uploads` lists your uploads, newest first (same fields as the upload response). The API does not document a processing-status endpoint; the list confirms the file was stored.

### 6. (Optional) Download a stored file

`GET https://app.intelibly.com/api/csv_uploads/{id}/download` returns `data.url` (temporary HTTPS URL), `data.expires_in` (typically 3600 seconds) and `data.filename`. Fetch `url` with a plain GET before it expires; no Bearer token is needed on that URL. `404` if the upload is not found.

### 7. (Optional) Delete a stored file

`DELETE https://app.intelibly.com/api/csv_uploads/{id}` permanently removes the file and returns `204 No Content`. `404` if not found. Only delete when the user explicitly asks.

## Error handling summary

200 success (list, download URL, template); 201 created; 204 deleted; 400 bad request; 401 authentication required or token invalid/expired (get a new token); 404 not found; 422 validation failed; 500 unexpected server error. Check the HTTP status first, then `errors.detail` or field-level `errors`.