> ## Documentation Index > Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a doctor account > Create a new doctor account for the authenticated institution. If `internalCode` is provided it acts as an idempotency key — submitting the same value twice returns 409. ## OpenAPI ````yaml /scribe-api/openapi-institutional.json post /v1/institutional/accounts openapi: 3.1.0 info: title: Scribe Public API description: >- External-facing REST API for integrating with the Telepatia platform. Authenticate with API keys, set consultation context, and look up scribe sessions. version: 0.1.0 servers: - url: https://scribe-api.telepatia.ai description: Production security: - BearerAuth: [] paths: /v1/institutional/accounts: post: tags: - Institutional - Institutional summary: Create a doctor account description: >- Create a new doctor account for the authenticated institution. If `internalCode` is provided it acts as an idempotency key — submitting the same value twice returns 409. operationId: api_institutional_account_created_v1_institutional_accounts_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAccountRequest' example: apiKeyConfig: validForDays: 365 country: CO doctorSpecialties: - cardiology email: dr.juan@clinica.com institutionalBranchName: Sede Norte internalCode: DOC-001 language: es nameFull: Dr. Juan Pérez timeZone: America/Bogota responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CreateAccountResponse' '400': description: >- Bad Request — invalid parameters, validation failures, or missing fields. content: application/json: examples: parameter_missing: summary: Missing required field value: error: type: invalid_request_error code: parameter_missing message: name is required. param: name parameter_invalid: summary: Invalid field value value: error: type: invalid_request_error code: parameter_invalid message: >- idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code. param: idCountry account_invalid: summary: Invalid account value: error: type: invalid_request_error code: account_invalid message: Account has no valid authId. schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized — missing or invalid API key. content: application/json: examples: authentication_required: summary: Invalid or missing API key value: error: type: authentication_error code: authentication_required message: Invalid API key. schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict — resource already exists or is in a conflicting state. content: application/json: examples: resource_conflict: summary: Resource conflict value: error: type: invalid_request_error code: resource_conflict message: >- consultationInternalId is already in use by a different consultation. param: consultationInternalId schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable — an external dependency is down. content: application/json: examples: service_unavailable: summary: External service unavailable value: error: type: api_error code: service_unavailable message: >- Unable to generate verification code. Please try again later. schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: CreateAccountRequest: properties: email: type: string maxLength: 254 title: Email examples: - dr.juan@clinica.com doctorSpecialties: items: $ref: '#/components/schemas/MedicalSpecialty' type: array minItems: 1 title: Doctorspecialties description: >- Accepts either the specialty key ('CARDIOLOGY') or value ('cardiology'); always persisted as the value. examples: - - cardiology country: anyOf: - type: string - type: 'null' title: Country description: >- Country as ISO 3166-1 alpha-2 (e.g. 'CO', 'BR'). Also accepts alpha-3 ('COL') or the English country name ('COLOMBIA'); all are normalized to the alpha-2 code Telepatia stores. Omit to inherit the institution's country. examples: - CO language: anyOf: - type: string - type: 'null' title: Language description: >- Account UI/content language as ISO 639-1 (e.g. 'es', 'pt', 'en'). Omit to inherit the institution's language. examples: - es timeZone: anyOf: - type: string - type: 'null' title: Timezone description: >- IANA time zone (e.g. 'America/Bogota', 'America/Sao_Paulo'). Omit to inherit the institution's time zone. examples: - America/Bogota nameFull: anyOf: - type: string maxLength: 500 - type: 'null' title: Namefull examples: - Dr. Juan Pérez institutionalBranchName: anyOf: - type: string maxLength: 255 - type: 'null' title: Institutionalbranchname examples: - Sede Norte internalCode: anyOf: - type: string maxLength: 128 - type: 'null' title: Internalcode description: >- Idempotency key scoped to the institution. Re-submitting the same value returns 409 if the account already exists. Omit to have the server generate a UUID v7 (no idempotency when generated); the value is returned in the response. examples: - DOC-001 apiKeyConfig: anyOf: - $ref: '#/components/schemas/ApiKeyConfig' - type: 'null' description: >- Optional API key settings. Omit to mint a key valid for 365 days (1 year). type: object required: - email - doctorSpecialties title: CreateAccountRequest description: Request body for creating an institutional doctor account. examples: - apiKeyConfig: validForDays: 365 country: CO doctorSpecialties: - cardiology email: dr.juan@clinica.com institutionalBranchName: Sede Norte internalCode: DOC-001 language: es nameFull: Dr. Juan Pérez timeZone: America/Bogota CreateAccountResponse: properties: id: type: string title: Id description: >- Account publicId (acc_*). Use this as the identifier in subsequent API calls. examples: - acc_a1b2c3d4e5f6g7h8 email: type: string title: Email examples: - dr.juan@clinica.com apiKey: type: string title: Apikey description: >- Raw secret API key for this account. Shown only once — store it securely. examples: - publishableApiKey: anyOf: - type: string - type: 'null' title: Publishableapikey description: >- Raw publishable (pk_) key for the browser/embed exchange flow. Exchange-only (cannot call the API directly) and shown only once — minted alongside the secret key. examples: - internalCode: type: string title: Internalcode description: >- Institution-scoped code for this account. Echoes the request value when supplied; otherwise a server-generated UUID v7. Always present — store it to fetch the account later via GET /accounts/{internalCode}. examples: - DOC-001 expiresAt: anyOf: - type: string - type: 'null' title: Expiresat description: >- UTC timestamp when this API key expires. Always present for institutional keys. examples: - '2027-06-17T00:00:00Z' apiKeyExpiresInDays: type: integer title: Apikeyexpiresindays description: >- API key lifetime in days that was applied (the validForDays used, default 365). examples: - 365 type: object required: - id - email - apiKey - internalCode - expiresAt - apiKeyExpiresInDays title: CreateAccountResponse description: Response body after creating an institutional doctor account. examples: - apiKey: apiKeyExpiresInDays: 365 email: dr.juan@clinica.com expiresAt: '2027-06-17T00:00:00Z' id: acc_a1b2c3d4e5f6g7h8 internalCode: DOC-001 publishableApiKey: ErrorResponse: description: Standardized error response envelope. properties: error: $ref: '#/components/schemas/ErrorDetail' required: - error title: ErrorResponse type: object MedicalSpecialty: type: string enum: - acupuncture - alternativeMedicine - ayurvedicMedicine - chiropractic - herbalMedicine - homeopathy - naturopathy - traditionalChineseMedicine - cosmeticDentistry - dentistry - developmentalBehavioralPediatrics - endodontics - forensicDentistry - maxillofacialProsthodontics - oralMaxillofacialSurgery - oralMedicine - oralPathology - oralSurgery - orthodontics - pediatricDentistry - periodontics - prosthodontics - addictionPsychiatry - adolescentMedicine - aerospaceMedicine - allergyImmunology - andrology - anesthesiology - anesthesiologyCriticalCare - bariatricSurgery - breastRadiology - breastSurgery - cardiacSurgery - cardiovascularSurgery - cardiology - cardiovascularDisease - cardiovascularRiskProgram - childAbusePediatrics - childAdolescentPsychiatry - childNeurology - childWelfareSocialWork - clinicalNeurophysiology - clinicalSocialWork - colorectalSurgery - communityMedicine - communitySocialWork - consultationLiaisonPsychiatry - cosmeticDermatology - craniofacialTrauma - dermatology - dermoscopy - diabetes - diagnosticRadiology - electrophysiology - emergencyCriticalCare - emergencyMedicine - emergencyPsychiatry - endocrineSurgery - endocrinology - epilepsy - facialPlasticSurgery - familyMedicine - familySocialWork - footAnkleSurgery - forensicPsychiatry - forensicSocialWork - gastroenterology - generalMedicine - generalMedicinePsychiatry - generalSurgery - geriatricMedicine - geriatricPsychiatry - geriatricSocialWork - ginecology - gynecologicOncology - gynecologicSurgery - gynecology - handSurgery - headNeckSurgery - headacheMedicine - heartFailureTransplantCardiology - hematology - hepatobiliarySurgery - hipKneeSurgery - hospitalist - infectiousDisease - internalCriticalCare - internalMedicine - interventionalCardiology - interventionalRadiology - maternalFetalMedicine - medicalSocialWork - militarySocialWork - minimallyInvasiveGynecologicSurgery - mohsSurgery - musculoskeletalRadiology - neonatology - nephrology - neurocriticalCare - neuroimmunology - neurology - neuromuscularMedicine - neuroradiology - neurorehabilitation - neurosurgery - neurotology - nuclearMedicine - obstetrics - obstetricsGynecology - occupationalMedicine - occupationalSocialWork - oculoplasticSurgery - oncology - oncologySocialWork - ophthalmology - orthopedicHandSurgery - orthopedicSportsMedicine - orthopedicTrauma - orthopedics - otolaryngology - painMedicine - palliativeMedicine - palliativeSocialWork - pediatricAllergyImmunology - pediatricAnesthesiology - pediatricCardiology - pediatricCriticalCare - pediatricDermatology - pediatricEmergencyMedicine - pediatricEndocrinology - pediatricENT - pediatricGastroenterology - pediatricHematologyOncology - pediatricInfectiousDisease - pediatricNephrology - pediatricNeurology - pediatricCardiacSurgery - pediatricOncology - pediatricOphthalmology - pediatricOrthopedics - pediatricPalliativeCare - pediatricPulmonology - pediatricRadiology - pediatricRheumatology - pediatricSocialWork - pediatricSurgery - pediatricTrauma - pediatricUrology - pediatrics - perinatalPsychiatry - physicalMedicineRehab - plasticSurgery - prenatalCareProgram - preventiveMedicine - psychiatricSocialWork - psychiatry - psychosomaticMedicine - publicHealth - pulmonaryDisease - pulmonology - radiationOncologist - radiationOncology - reproductiveEndocrinology - retinaSurgery - rheumatology - riasProgram - manager - schoolSocialWork - shoulderElbowSurgery - sleepMedicine - socialWork - spinalCordInjury - spinalTrauma - spineSurgery - sportsMedicine - substanceAbuseSocialWork - surgicalOncology - telemedicine - thoracicSurgery - transplantHepatology - transplantSurgery - traumaSurgery - traumatology - triage - unknown - urgentCare - urologicOncology - urology - vascularSurgery - nursing - clinicalNutrition - eatingDisorderNutrition - gastroenterologicNutrition - geriatricNutrition - nutrition - oncologyNutrition - pediatricNutrition - renalNutrition - sportsNutrition - clinicalPsychology - counselingPsychology - developmentalPsychology - forensicPsychology - geropsychology - healthPsychology - industrialOrganizationalPsychology - militaryPsychology - neuropsychology - positivePsychology - psychology - rehabilitationPsychology - schoolPsychology - sportsPsychology - occupationalTherapy - physicalTherapy - respiratoryTherapy - speechTherapy - therapy - other title: MedicalSpecialty ApiKeyConfig: properties: validForDays: type: integer maximum: 365 minimum: 1 title: Validfordays description: API key lifetime in days (1–365). Defaults to 365 (1 year). default: 365 examples: - 365 type: object title: ApiKeyConfig description: Configuration for the API key minted with the new account. ErrorDetail: description: Error detail with machine-readable codes and human-readable message. properties: type: description: Broad error category for high-level handling. examples: - invalid_request_error title: Type type: string code: description: Machine-readable error code. Clients should switch on this value. examples: - parameter_invalid title: Code type: string message: description: Human-readable error message ending with a period. examples: - >- idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code. title: Message type: string param: anyOf: - type: string - type: 'null' default: null description: The request field that caused the error, if applicable. examples: - idCountry title: Param details: anyOf: - additionalProperties: true type: object - type: 'null' default: null description: Optional structured, machine-readable context for the error. examples: - pendingConsultations: - sessionId: abc123 url: https://... title: Details required: - type - code - message title: ErrorDetail type: object securitySchemes: BearerAuth: type: http scheme: bearer description: API key passed as a Bearer token ````