> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Referring Provider > Creates a new referring provider record in your EMR system. ### Request Parameters #### Required Fields * **first\_name** (string, required): Provider's first name * **last\_name** (string, required): Provider's last name * **npi** (string, required): National Provider Identifier #### Optional Fields * **phone** (string): Contact phone number in XXX-XXX-XXXX format * **fax** (string): Fax number in XXX-XXX-XXXX format * **email** (string): Contact email address * **address** (string): Street address * **city** (string): City name * **state** (string): State abbreviation (e.g., "IL", "CA") * **zip\_code** (string): ZIP code ### Phone and Fax Format Phone and fax numbers must be provided in **XXX-XXX-XXXX** format. If the format is incorrect, you will receive a 400 error. ```json theme={null} // Valid "phone": "312-555-1234" // Invalid "phone": "3125551234" "phone": "(312) 555-1234" ``` ### Example Request ```bash theme={null} curl -X POST https://api.usecobalt.com/v1/referring-providers \ -H 'Content-Type: application/json' \ -H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \ -H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \ -H 'access_token: 493JKLHIU98789hLKH9HHJH' \ -d '{ "first_name": "John", "last_name": "Smith", "npi": "1234567890", "phone": "312-555-1234", "fax": "312-555-5678", "email": "john.smith@example.com", "address": "123 Main St", "city": "Chicago", "state": "IL", "zip_code": "60601" }' ``` ### Example Response ```json theme={null} { "success": true, "message": "Referring provider processing. A webhook event will be sent upon completion.", "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a", "job_id": 12345 } ``` The response includes: * **referring\_provider\_id**: Unique identifier for the created referring provider record (UUID without dashes) * **job\_id**: Job execution identifier for tracking the async operation ### Error Responses #### Missing Required Field ```json theme={null} { "success": false, "message": "Missing required fields: npi." } ``` #### Invalid Phone Format ```json theme={null} { "success": false, "message": "Phone number must be in XXX-XXX-XXXX format." } ``` #### Invalid Fax Format ```json theme={null} { "success": false, "message": "Fax number must be in XXX-XXX-XXXX format." } ``` ### Webhook Notifications When the referring provider processing is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like: #### Success ```json theme={null} { "id": "evt_1J9X2q2eZvKYlo2CluR9g9gV", "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz", "object": "event", "created": "2025-01-18T10:30:00Z", "type": "referring_provider.created", "job_id": "12345", "data": { "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a", "ehr_id": "350143", "first_name": "John", "last_name": "Smith", "npi": "1234567890" } } ``` #### Failure - Invalid NPI ```json theme={null} { "id": "evt_1J9X2q2eZvKYlo2CluR9g9gW", "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz", "object": "event", "created": "2025-01-18T10:35:00Z", "type": "referring_provider.failed", "job_id": "12345", "data": { "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a", "first_name": "John", "last_name": "Smith", "npi": "1234567890", "failure_reason": "Invalid NPI: 1234567890. The NPI number is not valid.", "error_type": "invalid_npi" } } ``` #### Failure - ECW Validation Error ```json theme={null} { "id": "evt_1J9X2q2eZvKYlo2CluR9g9gX", "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz", "object": "event", "created": "2025-01-18T10:40:00Z", "type": "referring_provider.failed", "job_id": "12345", "data": { "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a", "first_name": "John", "last_name": "Smith", "npi": "1234567890", "failure_reason": "Unable to create referring provider in eCW. ECW rejected the request. Please verify all required fields are provided and the provider doesn't already exist.", "error_type": "ecw_validation_failure" } } ``` #### Failure - Other Errors ```json theme={null} { "id": "evt_1J9X2q2eZvKYlo2CluR9g9gY", "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz", "object": "event", "created": "2025-01-18T10:45:00Z", "type": "referring_provider.failed", "job_id": "12345", "data": { "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a", "first_name": "John", "last_name": "Smith", "npi": "1234567890", "failure_reason": "Failed to create referring provider" } } ``` Referring provider creation is asynchronous. Store the returned referring\_provider\_id and listen for webhooks to determine the final status. ## Usage with Patient Creation Once created, you can use the `referring_provider_id` when creating patients instead of providing referring provider names. See the [Create Patient](/api-reference/patients/create) documentation for details on using `referring_provider_id`. ## Notes * NPI validation is performed by the EMR system (e.g., eClinicalWorks) * Some EMRs may reject duplicate providers with the same NPI * Phone and fax numbers are normalized before being sent to the EMR * The `ehr_id` returned in the success webhook is the provider's ID in your EMR system ## OpenAPI ````yaml POST /referring-providers openapi: 3.0.0 info: title: Cobalt API version: 1.0.1 description: API for interacting with Cobalt's EHR integration services servers: - url: https://api.usecobalt.com/v1 security: - ClientCredentials: [] ClientSecret: [] AccessToken: [] paths: /referring-providers: post: tags: - Referring Providers summary: Create Referring Provider description: Creates a new referring provider record in your EMR system. operationId: createReferringProvider requestBody: required: true content: application/json: schema: type: object required: - first_name - last_name - npi properties: first_name: type: string description: Provider's first name last_name: type: string description: Provider's last name npi: type: string description: National Provider Identifier phone: type: string description: Contact phone number in XXX-XXX-XXXX format fax: type: string description: Fax number in XXX-XXX-XXXX format email: type: string description: Contact email address address: type: string description: Street address city: type: string description: City name state: type: string description: State abbreviation (e.g., IL, CA) zip_code: type: string description: ZIP code responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean message: type: string referring_provider_id: type: string description: Cobalt referring provider ID (UUID without dashes) job_id: type: integer description: Job execution identifier for tracking the async operation '400': description: Bad request - Missing required fields or invalid format content: application/json: schema: type: object properties: success: type: boolean message: type: string '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean message: type: string '404': description: User not found content: application/json: schema: type: object properties: success: type: boolean message: type: string '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean message: type: string components: securitySchemes: ClientCredentials: type: apiKey in: header name: client_id ClientSecret: type: apiKey in: header name: client_secret AccessToken: type: apiKey in: header name: access_token ````