openapi: 3.2.0 info: title: Reference Organization External Providers API version: 1.0.0 servers: - url: https://pre-api.joincandidhealth.com description: Production - url: https://pre-api-staging.joincandidhealth.com description: Staging - url: https://sandbox-pre-api.joincandidhealth.com description: CandidSandbox - url: https://staging-pre-api.joincandidhealth.com description: CandidStaging - url: http://localhost:4000 description: Local - url: https://api.joincandidhealth.com description: Production - url: https://api-staging.joincandidhealth.com description: Staging - url: https://sandbox-api.joincandidhealth.com description: CandidSandbox - url: https://staging-api.joincandidhealth.com description: CandidStaging - url: http://localhost:5050 description: Local tags: - name: Organization External Providers paths: /organization-external-providers/v1/{id}: get: operationId: get summary: Get description: Gets an organization external provider by ID. tags: - Organization External Providers parameters: - name: id in: path required: true schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderId' - name: Authorization in: header description: OAuth authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProvider' '404': description: Error response with status 404 content: application/json: schema: type: object properties: errorName: type: string enum: - NotFoundError content: $ref: '#/components/schemas/type_pre-encounter_common_ErrorBase4xx' required: - errorName - content /organization-external-providers/v1: get: operationId: getMulti summary: Get Multi description: Searches for organization external providers that match the query parameters. tags: - Organization External Providers parameters: - name: limit in: query required: false schema: type: integer - name: page_token in: query required: false schema: $ref: '#/components/schemas/type_pre-encounter_common_PageToken' - name: sort_field in: query description: Defaults to name.family. required: false schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderSortField' - name: sort_direction in: query description: Defaults to ascending. required: false schema: $ref: '#/components/schemas/type_pre-encounter_common_SortDirection' - name: npi in: query required: false schema: type: string - name: type in: query required: false schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderType' - name: first_name in: query required: false schema: type: string - name: last_name in: query required: false schema: type: string - name: Authorization in: header description: OAuth authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderPage' post: operationId: create summary: Create description: Creates a new organization external provider. BadRequestError is returned when the NPI is already in use. tags: - Organization External Providers parameters: - name: Authorization in: header description: OAuth authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProvider' '400': description: Error response with status 400 content: application/json: schema: type: object properties: errorName: type: string enum: - BadRequestError content: $ref: '#/components/schemas/type_pre-encounter_common_ErrorBase4xx' required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_MutableOrganizationExternalProvider' /organization-external-providers/v1/{id}/{version}: put: operationId: update summary: Update description: Updates an organization external provider. The path must contain the next version number to prevent race conditions. For example, if the current version of the provider is n, you will need to send a request to this endpoint with `/{id}/n+1` to update the provider. Updating historic versions is not supported. BadRequestError is returned when the NPI is already in use by another provider. tags: - Organization External Providers parameters: - name: id in: path required: true schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderId' - name: version in: path required: true schema: type: string - name: Authorization in: header description: OAuth authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProvider' '400': description: Error response with status 400 content: application/json: schema: type: object properties: errorName: type: string enum: - BadRequestError content: $ref: '#/components/schemas/type_pre-encounter_common_ErrorBase4xx' required: - errorName - content '404': description: Error response with status 404 content: application/json: schema: type: object properties: errorName: type: string enum: - NotFoundError content: $ref: '#/components/schemas/type_pre-encounter_common_ErrorBase4xx' required: - errorName - content '409': description: Error response with status 409 content: application/json: schema: type: object properties: errorName: type: string enum: - VersionConflictError content: $ref: '#/components/schemas/type_pre-encounter_common_VersionConflictErrorBody' required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_MutableOrganizationExternalProvider' delete: operationId: deactivate summary: Deactivate description: Sets an organization external provider as deactivated. The path must contain the most recent version plus 1 to prevent race conditions. Deactivating historic versions is not supported. tags: - Organization External Providers parameters: - name: id in: path required: true schema: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderId' - name: version in: path required: true schema: type: string - name: Authorization in: header description: OAuth authentication required: true schema: type: string responses: '200': description: Successful response '404': description: Error response with status 404 content: application/json: schema: type: object properties: errorName: type: string enum: - NotFoundError content: $ref: '#/components/schemas/type_pre-encounter_common_ErrorBase4xx' required: - errorName - content '409': description: Error response with status 409 content: application/json: schema: type: object properties: errorName: type: string enum: - VersionConflictError content: $ref: '#/components/schemas/type_pre-encounter_common_VersionConflictErrorBody' required: - errorName - content /organization-external-providers/v1/updates/scan: get: operationId: scan summary: Scan description: 'Scans up to 1000 organization external provider updates. The since query parameter is inclusive, and the result list is ordered by updatedAt ascending. **Polling Pattern:** To continuously poll for updates without gaps: 1. Make your initial request with a `since` timestamp (e.g., `since=2020-01-01T13:00:00.000Z`) 2. The API returns 100 by default and up to 1000 records, sorted by `updated_at` ascending 3. Find the `updated_at` value from the last record in the response 4. Use that `updated_at` value as the `since` parameter in your next request 5. Repeat steps 2-4 to ingest updates until you receive an empty list **Important Notes:** - The `since` parameter is inclusive, so you may receive the last record from the previous batch again (you can deduplicate by ID and version) - All records include `updated_at`, `id`, `version`, `deactivated`, and `updating_user` fields for tracking changes - Timestamps have millisecond resolution for precise ordering' tags: - Organization External Providers parameters: - name: since in: query required: true schema: type: string format: date-time - name: maxResults in: query required: false schema: type: integer - name: Authorization in: header description: OAuth authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: type: array items: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProvider' components: schemas: type_pre-encounter_common_HumanName: type: object properties: family: type: string given: type: array items: type: string use: $ref: '#/components/schemas/type_pre-encounter_common_NameUse' period: $ref: '#/components/schemas/type_pre-encounter_common_Period' suffix: type: string required: - family - given - use title: HumanName type_pre-encounter_organizationExternalProviders_v1_LicenseType: type: string enum: - MD - NP - PA - LMFT - LCPC - LCSW - PMHNP - FNP - LPCC - DO - RD - SLP - APRN - LPC - PHD - PSYD - LMSW - LMHC - OTHER_MASTERS - BCBA - UNKNOWN - RPH - PHT - LAC - LMT - DC - ND - MA - PT - IBCLC - RN - DPT - LCMHC - CNM - RNFA - ACSW - APC - BCABA - BHA - OD - DPM - DA - DDS - DEH - DMD - PTA - LCADC - LCAT - LCMHCS - LCMHCA - LCSWA - LICSW - LISW - LMFTS - LMFTA - LPCI - LSCSW - MHCA - MHT - RBT - RCSWI - RHMCI - LPN - OTD - OMS - MFTA - APCC - DNP - AGNPBC - ANP - FNPPP - LCSWR - ALC - RMFTI - LAMFT - LPCA - LSWI - CSW - CPC - LGMFT - LLPC - PLPC - PLMFT - LMHCA - CIT - CT - MFT - LSW - PLMHP - PCMSW - LMHP - OTR/L - RPA - COTA - CRNP - SLP-CF - NP-C - PA-C - AMFT - CDN - CGC - CNS - MDPHD - AuD - ATC - LAT title: LicenseType type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderId: type: string format: uuid description: The unique identifier for an OrganizationExternalProvider in the database title: OrganizationExternalProviderId type_pre-encounter_common_SortDirection: type: string enum: - asc - desc title: SortDirection type_pre-encounter_common_NameUse: type: string enum: - USUAL - OFFICIAL - TEMP - NICKNAME - ANONYMOUS - OLD - MAIDEN title: NameUse type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderType: type: string enum: - REFERRING - PRIMARY - TREATING title: OrganizationExternalProviderType type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderPage: type: object properties: next_page_token: $ref: '#/components/schemas/type_pre-encounter_common_PageToken' prev_page_token: $ref: '#/components/schemas/type_pre-encounter_common_PageToken' total: type: integer items: type: array items: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProvider' required: - total - items title: OrganizationExternalProviderPage type_pre-encounter_common_ErrorBase4xx: type: object properties: message: type: string data: description: Any type required: - message title: ErrorBase4xx type_pre-encounter_common_AddressUse: type: string enum: - HOME - WORK - TEMP - OLD - BILLING title: AddressUse type_pre-encounter_common_VersionConflictErrorBody: type: object properties: message: type: string data: description: Any type latest_version: type: integer required: - message title: VersionConflictErrorBody type_pre-encounter_common_PageToken: type: string description: A token that can be used to retrieve the next or previous page of results title: PageToken type_pre-encounter_common_OrganizationId: type: string description: The unique identifier for an Organization in the database title: OrganizationId type_pre-encounter_organizationExternalProviders_v1_MutableOrganizationExternalProvider: type: object properties: name: $ref: '#/components/schemas/type_pre-encounter_common_HumanName' types: type: array items: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderType' npi: type: string tax_id: type: string taxonomy_code: type: string phone_number: type: string other_phone_numbers: type: array items: type: string fax_number: type: string other_fax_numbers: type: array items: type: string emails: type: array items: type: string license_type: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_LicenseType' addresses: type: array items: $ref: '#/components/schemas/type_pre-encounter_common_Address' required: - name - types description: An object representing an organization-level external provider. title: MutableOrganizationExternalProvider type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProvider: type: object properties: organization_id: $ref: '#/components/schemas/type_pre-encounter_common_OrganizationId' description: The organization that owns this object. deactivated: type: boolean description: True if the object is deactivated. Deactivated objects are not returned in search results but are returned in all other endpoints including scan. version: type: integer description: The version of the object. Any update to any property of an object object will create a new version. updated_at: type: string format: date-time updating_user_id: $ref: '#/components/schemas/type_pre-encounter_common_UserId' description: The user ID of the user who last updated the object. name: $ref: '#/components/schemas/type_pre-encounter_common_HumanName' types: type: array items: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderType' npi: type: string tax_id: type: string taxonomy_code: type: string phone_number: type: string other_phone_numbers: type: array items: type: string fax_number: type: string other_fax_numbers: type: array items: type: string emails: type: array items: type: string license_type: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_LicenseType' addresses: type: array items: $ref: '#/components/schemas/type_pre-encounter_common_Address' id: $ref: '#/components/schemas/type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderId' required: - organization_id - deactivated - version - updated_at - updating_user_id - name - types - id description: An OrganizationExternalProvider object with immutable server-owned properties. title: OrganizationExternalProvider type_pre-encounter_common_UserId: type: string description: The unique identifier for a User in the database title: UserId type_pre-encounter_organizationExternalProviders_v1_OrganizationExternalProviderSortField: type: string description: 'The field to order by. Valid values are keys on the provider object (e.g., name.family, npi, updatedAt, createdAt) or a special ordering "similar_name:" (Ex: similar_name:John). Similar name ordering uses trigrams to fuzzy match provider name to the search criteria.' title: OrganizationExternalProviderSortField type_pre-encounter_common_Period: type: object properties: start: type: string format: date end: type: string format: date title: Period type_pre-encounter_common_Address: type: object properties: use: $ref: '#/components/schemas/type_pre-encounter_common_AddressUse' line: type: array items: type: string city: type: string state: type: string postal_code: type: string country: type: string county: type: string period: $ref: '#/components/schemas/type_pre-encounter_common_Period' required: - use - line - city - state - postal_code - country title: Address securitySchemes: OAuthScheme: type: http scheme: bearer description: OAuth 2.0 authentication