openapi: 3.2.0 info: title: Reference Organization 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 Providers paths: /api/organization-providers/v3/{organization_provider_id}: get: operationId: get summary: Get organization provider tags: - Organization Providers parameters: - name: organization_provider_id in: path required: true schema: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderId' - 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_organization-providers_v3_OrganizationProviderV2' '404': description: Error response with status 404 content: application/json: schema: type: object properties: errorName: type: string enum: - EntityNotFoundError content: $ref: '#/components/schemas/type_commons_EntityNotFoundErrorMessage' required: - errorName - content patch: operationId: update summary: Update organization provider tags: - Organization Providers parameters: - name: organization_provider_id in: path required: true schema: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderId' - 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_organization-providers_v3_OrganizationProviderV2' '404': description: Error response with status 404 content: application/json: schema: type: object properties: errorName: type: string enum: - EntityNotFoundError content: $ref: '#/components/schemas/type_commons_EntityNotFoundErrorMessage' required: - errorName - content '422': description: Error response with status 422 content: application/json: schema: type: object properties: errorName: type: string enum: - UpdatesDisabledDueToExternalSystemIntegrationError content: $ref: '#/components/schemas/type_commons_UpdatesDisabledDueToExternalSystemIntegrationErrorMessage' required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_organization-providers_v3_OrganizationProviderUpdateV2' /api/organization-providers/v3: get: operationId: get_multi summary: Get all organization providers tags: - Organization Providers parameters: - name: limit in: query description: Limit the number of results returned. Defaults to 100. required: false schema: type: integer - name: search_term in: query description: Filter to a name or a part of a name. required: false schema: type: string - name: npi in: query description: Filter to a specific NPI. required: false schema: type: string - name: is_rendering in: query description: Filter to only rendering providers. required: false schema: type: boolean - name: is_billing in: query description: Filter to only billing providers. required: false schema: type: boolean - name: organization_provider_ids in: query description: Filter to the provided organization provider IDs. required: false schema: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderId' - name: page_token in: query description: The page token to continue paging through a previous request. required: false schema: $ref: '#/components/schemas/type_commons_PageToken' - name: sort in: query description: Defaults to PROVIDER_NAME_ASC. required: false schema: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderSortOptions' - name: organization_id in: query description: Filter to a specific organization's providers. If not provided, defaults to the requesting user's organization. required: false schema: $ref: '#/components/schemas/type_commons_OrganizationId' - 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_organization-providers_v3_OrganizationProviderPageV2' post: operationId: create summary: Create organization provider tags: - Organization 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_organization-providers_v3_OrganizationProviderV2' '422': description: Error response with status 422 content: application/json: schema: type: object properties: errorName: type: string enum: - UpdatesDisabledDueToExternalSystemIntegrationError content: $ref: '#/components/schemas/type_commons_UpdatesDisabledDueToExternalSystemIntegrationErrorMessage' required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_organization-providers_v3_OrganizationProviderCreateV2' /api/organization-providers/v3/{organization_provider_id}/attachments: put: operationId: upload_attachment summary: Upload provider attachment description: 'Uploads a file to the provider. Accepted file types are W9, PECOS_RECORD, and BANK_LETTER_OR_VOIDED_CHECK. Only one file per type is allowed per provider — uploading when a file of the same type already exists returns a 409.' tags: - Organization Providers parameters: - name: organization_provider_id in: path required: true schema: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderId' - 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_organization-providers_v3_ProviderAttachmentId' requestBody: content: multipart/form-data: schema: type: object properties: attachment_file: type: string format: binary description: The file to upload. file_type: $ref: '#/components/schemas/type_organization-providers_v3_ProviderAttachmentFileType' required: - attachment_file - file_type get: operationId: list_attachments summary: List provider attachments tags: - Organization Providers parameters: - name: organization_provider_id in: path required: true schema: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderId' - 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_organization-providers_v3_ProviderAttachment' /api/organization-providers/v3/attachments/download: get: operationId: download_attachment summary: Download provider attachment tags: - Organization Providers parameters: - name: attachment_id in: query required: true schema: $ref: '#/components/schemas/type_organization-providers_v3_ProviderAttachmentId' - 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_organization-providers_v3_ProviderAttachmentResponse' /api/organization-providers/v3/attachments/{attachment_id}: delete: operationId: delete_attachment summary: Delete provider attachment tags: - Organization Providers parameters: - name: attachment_id in: path required: true schema: $ref: '#/components/schemas/type_organization-providers_v3_ProviderAttachmentId' - name: Authorization in: header description: OAuth authentication required: true schema: type: string responses: '200': description: Successful response components: schemas: type_organization-providers_v3_OrganizationProviderV2: type: object properties: npi: type: string description: The NPI of the provider. This must be all digits [0-9] and exactly 10 characters long. is_rendering: type: boolean description: Whether the provider can be used to render services. is_billing: type: boolean description: Whether the provider can be used to bill services. first_name: type: string description: The first name of the provider, if the provider is an individual. last_name: type: string description: The last name of the provider, if the provider is an individual. organization_name: type: string description: The name of the provider, if the provider is an organization. provider_type: $ref: '#/components/schemas/type_organization-providers_v2_ProviderType' description: Whether the provider is an individual (NPPES Type 1) or organization (NPPES Type 2) provider. tax_id: type: string description: If the provider has a contract with insurance, this must be the same tax ID given to the payer on an IRS W-9 form completed during contracting. taxonomy_code: type: string description: A code designating classification and specialization. license_type: $ref: '#/components/schemas/type_organization-providers_v2_LicenseType' description: The type of license that the provider holds. addresses: type: array items: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderAddress' description: The addresses associated with this provider. employment_start_date: type: string format: date description: The employment start date for the provider. employment_termination_date: type: string format: date description: The employment termination date for the provider. organization_provider_id: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderId' description: Auto-generated ID set on creation. qualifications: type: array items: $ref: '#/components/schemas/type_identifiers_Identifier' description: Qualification given to a provider (PTAN, Medicaid Provider Id etc.). required: - npi - is_rendering - is_billing - provider_type - license_type - organization_provider_id - qualifications title: OrganizationProviderV2 type_organization-providers_v3_OrganizationProviderPageV2: type: object properties: prev_page_token: $ref: '#/components/schemas/type_commons_PageToken' next_page_token: $ref: '#/components/schemas/type_commons_PageToken' items: type: array items: $ref: '#/components/schemas/type_organization-providers_v3_OrganizationProviderV2' required: - items title: OrganizationProviderPageV2 type_organization-providers_v3_ProviderAttachmentFileType: type: string enum: - W9 - PECOS_RECORD - BANK_LETTER_OR_VOIDED_CHECK title: ProviderAttachmentFileType type_commons_Date: type: string description: ISO 8601 date; formatted YYYY-MM-DD (i.e. 2012-02-01) title: Date type_organization-providers_v3_OrganizationProviderUpdateV2: type: object properties: npi: type: string description: The NPI of the provider. This must be all digits [0-9] and exactly 10 characters long. is_rendering: type: boolean description: Whether the provider can be used to render services. is_billing: type: boolean description: Whether the provider can be used to bill services. first_name: type: string description: The first name of the provider, if the provider is an individual. last_name: type: string description: The last name of the provider, if the provider is an individual. organization_name: type: string description: The name of the provider, if the provider is an organization. provider_type: $ref: '#/components/schemas/type_organization-providers_v2_ProviderType' description: Whether the provider is an individual (NPPES Type 1) or organization (NPPES Type 2) provider. tax_id: type: string description: If the provider has a contract with insurance, this must be the same tax ID given to the payer on an IRS W-9 form completed during contracting. taxonomy_code: type: string description: A code designating classification and specialization. license_type: $ref: '#/components/schemas/type_organization-providers_v2_LicenseType' description: The type of license that the provider holds. addresses: type: array items: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderAddress' description: The addresses associated with this provider. employment_start_date: $ref: '#/components/schemas/type_commons_Date' description: The employment start date for the provider. employment_termination_date: $ref: '#/components/schemas/type_commons_Date' description: The employment termination date for the provider. qualifications: type: array items: $ref: '#/components/schemas/type_identifiers_UpdatableIdentifier' description: Provider's qualifications (medicare provider number, medicaid provider number, etc.) title: OrganizationProviderUpdateV2 type_organization-providers_v2_OrganizationProviderId: type: string format: uuid title: OrganizationProviderId type_commons_State: type: string enum: - AA - AE - AP - AL - AK - AS - AZ - AR - CA - CO - CT - DC - DE - FL - FM - GA - GU - HI - ID - IL - IN - IA - KS - KY - LA - ME - MD - MA - MH - MI - MN - MP - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - OH - OK - OR - PA - PR - PW - RI - SC - SD - TN - TX - UT - VI - VT - VA - WA - WV - WI - WY title: State type_commons_RemovableDateRangeOptionalEnd: oneOf: - type: object properties: type: type: string enum: - date_range description: 'Discriminator value: date_range' start_date: $ref: '#/components/schemas/type_commons_Date' end_date: $ref: '#/components/schemas/type_commons_Date' required: - type - start_date - type: object properties: type: type: string enum: - remove description: 'Discriminator value: remove' required: - type discriminator: propertyName: type title: RemovableDateRangeOptionalEnd type_identifiers_IdentifierId: type: string format: uuid title: IdentifierId type_organization-providers_v2_ProviderType: type: string enum: - INDIVIDUAL - ORGANIZATION title: ProviderType type_identifiers_IdentifierValue: oneOf: - type: object properties: type: type: string enum: - medicare_provider_identifier description: 'Discriminator value: medicare_provider_identifier' state: $ref: '#/components/schemas/type_commons_State' provider_number: type: string organization_service_facility_id: $ref: '#/components/schemas/type_organization-service-facilities_v2_OrganizationServiceFacilityId' description: When set, this identifier applies only to the given service facility. required: - type - state - provider_number - type: object properties: type: type: string enum: - medicaid_provider_identifier description: 'Discriminator value: medicaid_provider_identifier' state: $ref: '#/components/schemas/type_commons_State' provider_number: type: string organization_service_facility_id: $ref: '#/components/schemas/type_organization-service-facilities_v2_OrganizationServiceFacilityId' description: When set, this identifier applies only to the given service facility. required: - type - state - provider_number discriminator: propertyName: type title: IdentifierValue type_commons_StreetAddressLongZip: type: object properties: address1: type: string address2: type: string city: type: string state: $ref: '#/components/schemas/type_commons_State' zip_code: type: string description: 5-digit zip code zip_plus_four_code: type: string description: 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4 required: - address1 - city - state - zip_code - zip_plus_four_code title: StreetAddressLongZip type_organization-providers_v2_OrganizationProviderAddress: type: object properties: address: $ref: '#/components/schemas/type_commons_StreetAddressLongZip' description: The address of the provider address_type: $ref: '#/components/schemas/type_organization-providers_v2_AddressType' description: The address type of the provider required: - address - address_type title: OrganizationProviderAddress type_organization-service-facilities_v2_OrganizationServiceFacilityId: type: string format: uuid title: OrganizationServiceFacilityId type_commons_PageToken: type: string title: PageToken type_organization-providers_v3_OrganizationProviderCreateV2: type: object properties: npi: type: string description: The NPI of the provider. This must be all digits [0-9] and exactly 10 characters long. is_rendering: type: boolean description: Whether the provider can be used to render services. is_billing: type: boolean description: Whether the provider can be used to bill services. first_name: type: string description: The first name of the provider. Required when provider_type is INDIVIDUAL. Must not be set when provider_type is ORGANIZATION. last_name: type: string description: The last name of the provider. Required when provider_type is INDIVIDUAL. Must not be set when provider_type is ORGANIZATION. organization_name: type: string description: The name of the provider. Required when provider_type is ORGANIZATION. Must not be set when provider_type is INDIVIDUAL. provider_type: $ref: '#/components/schemas/type_organization-providers_v2_ProviderType' description: Whether the provider is an individual (NPPES Type 1) or organization (NPPES Type 2) provider. tax_id: type: string description: Required when is_billing is true. If the provider has a contract with insurance, this must be the same tax ID given to the payer on an IRS W-9 form completed during contracting. taxonomy_code: type: string description: A code designating classification and specialization. license_type: $ref: '#/components/schemas/type_organization-providers_v2_LicenseType' description: The type of license that the provider holds. addresses: type: array items: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderAddress' description: The addresses associated with this provider. employment_start_date: type: string format: date description: The employment start date for the provider. employment_termination_date: type: string format: date description: The employment termination date for the provider. qualifications: type: array items: $ref: '#/components/schemas/type_identifiers_IdentifierCreate' description: A provider's qualifications such as PTAN, Medicaid Provider Id, etc. required: - npi - is_rendering - is_billing - provider_type - license_type - qualifications title: OrganizationProviderCreateV2 type_organization-providers_v2_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 - OTA - LSSP - SLPA title: LicenseType type_commons_DateRangeOptionalEnd: type: object properties: start_date: $ref: '#/components/schemas/type_commons_Date' end_date: $ref: '#/components/schemas/type_commons_Date' required: - start_date title: DateRangeOptionalEnd type_organization-providers_v2_AddressType: type: string enum: - DEFAULT title: AddressType type_commons_UpdatesDisabledDueToExternalSystemIntegrationErrorMessage: type: object properties: message: type: string title: UpdatesDisabledDueToExternalSystemIntegrationErrorMessage type_organization-providers_v3_ProviderAttachment: type: object properties: provider_attachment_id: $ref: '#/components/schemas/type_organization-providers_v3_ProviderAttachmentId' organization_provider_id: $ref: '#/components/schemas/type_organization-providers_v2_OrganizationProviderId' file_name: type: string file_type: $ref: '#/components/schemas/type_organization-providers_v3_ProviderAttachmentFileType' required: - provider_attachment_id - organization_provider_id - file_name - file_type title: ProviderAttachment type_identifiers_UpdatableIdentifier: oneOf: - type: object properties: type: type: string enum: - add description: 'Discriminator value: add' period: $ref: '#/components/schemas/type_commons_DateRangeOptionalEnd' identifier_code: $ref: '#/components/schemas/type_identifiers_IdentifierCode' identifier_value: $ref: '#/components/schemas/type_identifiers_IdentifierValue' required: - type - identifier_code - identifier_value - type: object properties: type: type: string enum: - update description: 'Discriminator value: update' identifier_id: $ref: '#/components/schemas/type_identifiers_IdentifierId' identifier_code: $ref: '#/components/schemas/type_identifiers_IdentifierCode' identifier_value: $ref: '#/components/schemas/type_identifiers_IdentifierValue' period: $ref: '#/components/schemas/type_commons_RemovableDateRangeOptionalEnd' required: - type - identifier_id - type: object properties: type: type: string enum: - remove description: 'Discriminator value: remove' value: $ref: '#/components/schemas/type_identifiers_IdentifierId' required: - type - value discriminator: propertyName: type title: UpdatableIdentifier type_identifiers_IdentifierCreate: type: object properties: period: $ref: '#/components/schemas/type_commons_DateRangeOptionalEnd' identifier_code: $ref: '#/components/schemas/type_identifiers_IdentifierCode' identifier_value: $ref: '#/components/schemas/type_identifiers_IdentifierValue' required: - identifier_code - identifier_value title: IdentifierCreate type_organization-providers_v2_OrganizationProviderSortOptions: type: string enum: - provider_name:asc - provider_name:desc - npi:asc - npi:desc title: OrganizationProviderSortOptions type_organization-providers_v3_ProviderAttachmentId: type: string format: uuid title: ProviderAttachmentId type_commons_OrganizationId: type: string format: uuid title: OrganizationId type_identifiers_Identifier: type: object properties: period: $ref: '#/components/schemas/type_commons_DateRangeOptionalEnd' identifier_code: $ref: '#/components/schemas/type_identifiers_IdentifierCode' identifier_value: $ref: '#/components/schemas/type_identifiers_IdentifierValue' identifier_id: $ref: '#/components/schemas/type_identifiers_IdentifierId' required: - identifier_code - identifier_value - identifier_id title: Identifier type_commons_EntityNotFoundErrorMessage: type: object properties: id: type: string required: - id title: EntityNotFoundErrorMessage type_organization-providers_v3_ProviderAttachmentResponse: type: object properties: signed_download_url: type: string required: - signed_download_url title: ProviderAttachmentResponse type_identifiers_IdentifierCode: type: string enum: - MCR - MCD title: IdentifierCode securitySchemes: OAuthScheme: type: http scheme: bearer description: OAuth 2.0 authentication