Copy page

Partner API

Partner CSV Upload API

Overview

The Partner CSV Upload API lets you securely upload CSV files to Intelibly for storage and later use. Uploads are associated automatically with your organization based on your API credentials.

• Base URL (production): https://app.intelibly.com
• Base URL (staging/dev): provided separately for your environment

Typical integration flow

Code
1. POST /api/token
      → access_token

2. (Optional) GET /api/csv_uploads/template
      → header row for file generation

3. Generate your CSV using the recommended columns

4. POST /api/csv_uploads
      → multipart file upload
      → receive upload id

5. (Optional) GET /api/csv_uploads
      → confirm the file appears in your upload history

6. (Optional) GET /api/csv_uploads/{id}/download
      → verify stored contents via temporary URL

7. Refresh the access token before it expires (step 1)

Authentication

All endpoints require a Bearer access token obtained with the OAuth 2.0 client credentials grant.

Credentials

Intelibly will provide:

Obtain an access token

Code
POST /api/token
Content-Type: application/json

Request body

Code
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "grant_type": "client_credentials"
}

Successful response 200 OK

Code
{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error response 400 Bad Request

Code
{
  "error": "invalid_client"
}

or

Code
{
  "error": "invalid_request"
}

Using the access token

Include the token on every protected request:

Code
Authorization: Bearer YOUR_ACCESS_TOKEN

Tokens expire after approximately one hour. Request a new token when expires_in elapses; do not reuse expired tokens.

Endpoints

1. Upload a CSV file

Code
POST /api/csv_uploads
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: multipart/form-data

Form fields

Constraints

Example (cURL)

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

Successful response 201 Created

Code
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filename": "practices.csv",
    "file_size": 24576,
    "content_type": "text/csv",
    "inserted_at": "2026-07-21T18:30:00.000000Z"
  }
}

Error responses

Example validation error:

Code
{
  "errors": {
    "filename": ["must be a CSV file"]
  }
}

2. List uploaded files

Returns your uploaded files, newest first.

Code
GET /api/csv_uploads
Authorization: Bearer YOUR_ACCESS_TOKEN

Successful response 200 OK

Code
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "filename": "practices.csv",
      "file_size": 24576,
      "content_type": "text/csv",
      "inserted_at": "2026-07-21T18:30:00.000000Z"
    }
  ]
}

3. Get download URL for an uploaded file

Returns a time-limited URL to download a previously uploaded file.

Code
GET /api/csv_uploads/:id/download
Authorization: Bearer YOUR_ACCESS_TOKEN

Path parameters

Successful response 200 OK

Code
{
  "data": {
    "url": "https://...",
    "expires_in": 3600,
    "filename": "practices.csv"
  }
}

Use the returned url with a normal HTTP GET. No API Bearer token is required on the download URL itself. Download the file before the URL expires.

Error responses

4. Delete an uploaded file

Permanently removes an uploaded file.

Code
DELETE /api/csv_uploads/:id
Authorization: Bearer YOUR_ACCESS_TOKEN

Successful response 204 No Content

Error responses

5. Download CSV header template

Returns a CSV containing only the recommended header row. Useful when generating files programmatically.

Code
GET /api/csv_uploads/template
Authorization: Bearer YOUR_ACCESS_TOKEN

Successful response 200 OK

Code
Content-Type: text/csv
Content-Disposition: attachment; filename="partner_import.csv"

The response body is a single header row (see Recommended CSV format below).

Recommended CSV format

For practice and provider data, use the following header row (case-insensitive):

Code
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

Column reference

*Your Intelibly contact will confirm if internal location and provider IDs are required for your integration. The CSV Template Field Reference describes every field in detail, including the requirements for FinderCONNECT Button and FinderCONNECT Map.

Example row

Code
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
Sample Family Dental,frontdesk@example.com,www.example.com,Jordan Sample,Main Office,(210) 555-0123,100 Example St., San Antonio, TX 78229,,Dr. Alex Sample,Periodontics,,gold,,1234567893,Product Name

Error handling summary

Prefer checking HTTP status codes. Where present, read errors.detail or field-level errors for human-readable messages.

Security notes

• Store client_secret securely (environment variables / secrets manager). Never embed it in client-side applications or public repositories.
• Transmit credentials and tokens only over HTTPS.
• Use access tokens only for server-to-server automation; rotate credentials if compromised.
• Download URLs are short-lived; treat them as sensitive while valid.

Support

For credential provisioning or questions about the recommended CSV format, contact your Intelibly Provider Relations representative.