Skip to content

SPRY Developers

Create Onboarding Provider

Create Onboarding Provider¶

Creates an onboarding provider.

Endpoint¶

POST /v2/onboarding/providers

Request Body¶

Parameter	Type	Required	Description
`npi`	string	Yes	Checksum-valid NPI-1 resolved via NPPES.
`email`	string	Yes	Becomes the provider's EMR username at publish.
`clinics`	array of string	Yes	Onboarding clinic ids from GET /v2/onboarding/clinics.
`first_name`	string	No
`last_name`	string	No
`name_prefix`	string	No
`credential`	string	No
`dob`	string (date)	No	`YYYY-MM-DD`.
`gender`	string	No	Administrative gender. Only `M` and `F` are accepted here.
`phone`	string	No
`license_no`	string	No
`ptan`	string	No	Provider Transaction Access Number.
`sole_proprietor`	boolean	No
`taxonomies`	array of object	No	See Taxonomies.
`primary_taxonomy_code`	string	No	NUCC provider taxonomy code.
`online_booking`	array of object	No	Whether this record is bookable through online booking. See Online Booking.
`schedule`	array	No	The provider's onboarding schedule, passed through from onboarding's own shape.
`billing_profile_ids`	array of string	No	Billing profiles attached to this provider.
`direct_access_permitted`	boolean	No	Whether patients may book this provider without a referral. Defaults to `true`.
`home_health`	any	No	Home-health configuration object — `enabled`, `state_code`, `address`, `location`, `transport_mode`, drive/visit limits, `schedules[]`, `scheduling_overrides{}`. Passed through in onboarding's own shape.

Taxonomies¶

Parameter	Type	Required	Description
`code`	string	Yes
`desc`	string or null	No
`group_code`	string or null	No
`group_desc`	string or null	No
`license`	string or null	No
`primary`	boolean or null	No	Whether this is the provider's primary taxonomy.
`specialization`	string or null	No
`state`	string or null	No

Online Booking¶

Parameter	Type	Required	Description
`clinic_id`	string	Yes	The clinic this record belongs to.
`enabled`	boolean	Yes

Request¶

curl --location '{base_url}/v2/onboarding/providers' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "npi": "1740398215",
  "email": "m.delgado@example.com",
  "clinics": null,
  "first_name": "Morgan",
  "last_name": "Delgado",
  "name_prefix": null,
  "credential": "DPT",
  "dob": "1991-07-23",
  "gender": "M",
  "phone": "+1-555-0143",
  "license_no": "PT-30914",
  "ptan": null,
  "sole_proprietor": false,
  "taxonomies": [
    {
      "code": "97110",
      "desc": null,
      "group_code": null,
      "group_desc": null,
      "license": "PT-30914",
      "primary": true,
      "specialization": "PHYSICAL_THERAPY",
      "state": "OR"
    }
  ],
  "primary_taxonomy_code": null,
  "online_booking": [
    {
      "clinic_id": "5831",
      "enabled": true
    }
  ],
  "schedule": null,
  "billing_profile_ids": [],
  "direct_access_permitted": true,
  "home_health": null
}'

Response¶

Success Response¶

Code: 201 Created

{
  "id": "b41f7c92-5e08-4a13-8d6f-2c9147ab3e5d",
  "npi": "1740398215",
  "emr_user_id": null,
  "npi_verified": true,
  "first_name": "Morgan",
  "last_name": "Delgado",
  "name_prefix": null,
  "credential": "DPT",
  "dob": "1991-07-23",
  "gender": "M",
  "email": "m.delgado@example.com",
  "phone": "+1-555-0143",
  "license_no": "PT-30914",
  "ptan": null,
  "sole_proprietor": false,
  "taxonomies": [
    {
      "code": "97110",
      "desc": null,
      "group_code": null,
      "group_desc": null,
      "license": "PT-30914",
      "primary": true,
      "specialization": "PHYSICAL_THERAPY",
      "state": "OR"
    }
  ],
  "primary_taxonomy_code": null,
  "clinics": null,
  "online_booking": [
    {
      "clinic_id": "5831",
      "enabled": true
    }
  ],
  "schedule": null,
  "billing_profile_ids": [],
  "access_revoked": false,
  "direct_access_permitted": true,
  "home_health": null
}

The Location header carries the URL of the created resource.

Response Fields¶

Field	Type	Description
`id`	string	The onboarding record's UUID.
`npi`	string or null
`emr_user_id`	integer or null	The operational provider id once the record is published. `null` before publish.
`npi_verified`	boolean	Whether onboarding validated the NPI against NPPES.
`first_name`	string or null
`last_name`	string or null
`name_prefix`	string or null
`credential`	string or null
`dob`	string (date) or null	`YYYY-MM-DD`.
`gender`	string or null	Administrative gender. Only `M` and `F` are accepted here.
`email`	string or null
`phone`	string or null
`license_no`	string or null
`ptan`	string or null	Provider Transaction Access Number.
`sole_proprietor`	boolean or null
`taxonomies`	array of object	See Taxonomies.
`primary_taxonomy_code`	string or null	NUCC provider taxonomy code.
`clinics`	array of string
`online_booking`	array of object	Whether this record is bookable through online booking. See Online Booking.
`schedule`	array	The provider's onboarding schedule, passed through from onboarding's own shape.
`billing_profile_ids`	array of string	Billing profiles attached to this provider.
`access_revoked`	boolean	Whether the provider's onboarding access has been revoked.
`direct_access_permitted`	boolean or null	Whether patients may book this provider without a referral. Defaults to `true`.
`home_health`	any or null	Home-health configuration object — `enabled`, `state_code`, `address`, `location`, `transport_mode`, drive/visit limits, `schedules[]`, `scheduling_overrides{}`. Passed through in onboarding's own shape.

Taxonomies¶

Field	Type	Description
`code`	string
`desc`	string or null
`group_code`	string or null
`group_desc`	string or null
`license`	string or null
`primary`	boolean or null	Whether this is the provider's primary taxonomy.
`specialization`	string or null
`state`	string or null

Online Booking¶

Field	Type	Description
`clinic_id`	string	The clinic this record belongs to.
`enabled`	boolean

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`409 Conflict`	`conflict`	The record conflicts with existing state — see the endpoint's notes.
`412 Precondition Failed`	`precondition_failed`	`If-Match` is stale. Re-read the resource and retry.
`428 Precondition Required`	`precondition_required`	`If-Match` is required on this write.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.