openapi: 3.0.1 info: title: Real Dental Attachments API contact: name: '' email: '' version: v1 description: Services requests for Dental Attachments for both Provider and Payer users of the Optum Real Dental suite of products. termsOfService: '' x-shortDescription: Real Dental Attachments API servers: - url: https://sandbox-apigw.optum.com/dental/attachments/v1 description: '' tags: - name: Health Check description: Operations for checking the health of the service. - name: Create Attachments description: Operations for creating and uploading attachments. - name: Review Attachments description: Operations for retrieving attachments for review. - name: Image Intelligence description: Operations for enabling Image Intelligence for attachments. paths: /healthcheck: get: tags: - Health Check summary: Health Check Endpoint responses: '200': content: application/json: schema: type: object properties: Status: type: string example: Status: Service is healthy description: Service is healthy default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: A problem occurred. operationId: healthCheck security: - bearerAuth: [] /attachments/documents: post: tags: - Create Attachments summary: Create Attachments by Uploading Documents responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateAttachmentResponse' examples: singleFile: value: status: CLOSED createdAt: '2024-01-15T14:30:00Z' attachmentIds: - CHC#123456789055 attachmentControlNumber: CHC#507f1f77bcf86cd799439011 summary: Single file uploaded multipleFiles: value: status: CLOSED createdAt: '2024-01-15T14:30:00Z' attachmentIds: - CHC#123456358902 - CHC#122256789023 - CHC#133456789024 attachmentControlNumber: CHC#507f1f77bcf86cd799439011 summary: Multiple files uploaded description: Attachments created successfully default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: A problem occurred. description: "Create Attachments by uploading files along with required metadata in a single request.\ \ All attachments will be associated with a new Attachment Control Number and ClaimId and will\ \ be considered Closed upon completion of the request.\n\n**Request Format:**\n- Content-Type:\ \ `multipart/form-data`\n- The request consists of two parts:\n 1. `request` (JSON): Contains\ \ claim metadata\n 2. `files` (binary): One or more attachment files (1-10 files) \n\n**Example\ \ Request:**\n```\n--boundary\nContent-Disposition: form-data; name=\\\"request\\\"\nContent-Type:\ \ application/json\n\n{\n \\\"claimId\\\": \\\"CLM-2024-001234\\\",\n \\\"payerId\\\": \\\"\ ABC12\\\",\n \\\"providerNPI\\\": \\\"1234567890\\\",\n \\\"dateOfService\\\": \\\"2024-01-15\\\ \",\n \\\"patientLastName\\\": \\\"Atreides\\\",\n \\\"patientFirstName\\\": \\\"Paul\\\",\n\ \ \\\"patientDateOfBirth\\\": \\\"2000-01-01\\\",\n \\\"memberId\\\": \\\"44444444\\\"\n}\n\n\ --boundary\nContent-Disposition: form-data; name=\\\"files\\\"; filename=\\\"xray_image.pdf\\\"\ ;\n \nContent-Type: application/pdf\n\n[binary file content]\n\n--boundary--\n```\n\n**Supported\ \ File Types:** BMP, JPG/JPEG, TIFF, PNG, PDF, TXT, DOC/DOCX, DICOM, GIF, RTF\n\n**File Limits:**\ \ 1-10 files per request." operationId: createAttachments requestBody: content: multipart/form-data: schema: type: object required: - submitterId - billingProviderTaxId - claimId - payerId - providerNPI - dateOfService - patientLastName - patientFirstName - patientDateOfBirth - memberId - files properties: files: type: array items: type: string format: binary maxItems: 10 minItems: 1 description: Raw binary of the files to be uploaded as attachments claimId: type: string maxLength: 50 description: JSON property of request body property 'request' containing the claim ID associated with the attachments payerId: type: string pattern: ^[A-Za-z0-9]{5}$ description: JSON property of request body property 'request' containing the payer Id associated with the attachments memberId: type: string maxLength: 50 providerNPI: type: string pattern: ^[0-9]{10}$ description: JSON property of request body property 'request' containing the provider NPI associated with the attachments submitterId: type: string maxLength: 50 description: JSON property of request body property 'request' containing the submitter Id associated with the attachments. Requestor MUST have access to this submitter id. dateOfService: type: string format: date description: JSON property of request body property 'request' containing the first Date of Service associated with the attachments patientLastName: type: string maxLength: 75 patientFirstName: type: string maxLength: 50 patientDateOfBirth: type: string maxLength: 10 billingProviderTaxId: type: string maxLength: 50 description: JSON property of request body property 'request' containing the billing provider tax Id associated with the attachments. Requestor MUST have access to this billing provider tax id (TIN). encoding: files: contentType: application/octet-stream, image/bmp, image/x-ms-bmp, image/jpeg, image/pjpeg, image/tiff, image/x-tiff, image/png, application/pdf, text/plain, text/x-text, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/dicom, application/dicom+json, application/dicom+xml, image/gif, application/rtf, text,rtf request: contentType: application/json required: true security: - bearerAuth: [] /attachments/documents/search: post: tags: - Review Attachments summary: Search for Attachments by Ids responses: '200': content: multipart/form-data: schema: type: string format: binary description: Multipart response containing one or more attachment files. examples: multipleAttachments: value: "------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"\ file\"; filename=\"xray_1.pdf\"; attachmentControlNumber=\"507f1f77bcf86cd799439011\"\ ; attachmentId=\"023981023345\"\r\nContent-Type: application/pdf\r\n\r\n[binary file\ \ content]\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data;\ \ name=\"file\"; filename=\"report_2.pdf\"; attachmentControlNumber=\"507f1f77bcf86cd799439011\"\ ; attachmentId=\"023981023346\"\r\nContent-Type: application/pdf\r\n\r\n[binary file\ \ content]\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW--" summary: Multiple attachments response description: Search results from provided list of Attachment Identifiers headers: Content-Type: schema: type: string example: multipart/form-data; boundary=----WebKitFormBoundary0452a64cf6b94c2f9cc2c6f3da9ae864 description: Content type with multipart boundary Content-Length: schema: type: integer description: Total size of the multipart response body in bytes description: All raw files retrieved successfully (base64 encoded) default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: A problem occurred. description: For all of the requested Attachments by Id, get the original binary file with appropriate Content-Type and Content-Disposition headers for download. operationId: searchAttachments requestBody: content: application/json: schema: type: object required: - attachmentIds properties: attachmentIds: type: array items: type: string pattern: ^([A-Z]{3}#)?([0-9]{12}|[0-9a-fA-F]{24})$ maxItems: 10 minItems: 1 examples: searchByAttachmentIds: value: attachmentIds: - CHC#123456789055 - CHC#123456358902 - CHC#122256789023 summary: Search by Attachment Ids description: Example request body for searching attachments by a list of Attachment Ids searchByAttachmentControlNumber: value: attachmentIds: - CHC#507f1f77bcf86cd799439011 summary: Search by Attachment Control Number description: Example request body for searching attachments by Attachment Control Number (returns all attachments associated with the control number) required: true security: - bearerAuth: [] /attachments/documents/image-intelligence: post: tags: - Image Intelligence summary: Create Attachments by Uploading Documents and Enabling Image Intelligences responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateAttachmentResponse' examples: singleFile: value: status: CLOSED createdAt: '2024-01-15T14:30:00Z' attachmentIds: - CHC#123456789055 attachmentControlNumber: CHC#507f1f77bcf86cd799439011 imageIntelligenceTransactionId: 69122940fab78c16744c5cc2 summary: Single file uploaded with Optum Image Intelligence metadata successfully processed multipleFiles: value: status: CLOSED createdAt: '2024-01-15T14:30:00Z' attachmentIds: - CHC#123456358902 - CHC#122256789023 - CHC#133456789024 attachmentControlNumber: CHC#507f1f77bcf86cd799439011 imageIntelligenceTransactionId: 69122940fab78c16744c5cc2 summary: Multiple files uploaded with Optum Image Intelligence metadata successfully processed description: Attachments created successfully default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: A problem occurred. description: "Create Attachments by uploading files along with required metadata in a single request.\ \ All attachments will be associated with a new Attachment Control Number and ClaimId and will\ \ be considered Closed upon completion of the request.\n\n**Request Format:**\n- Content-Type:\ \ `multipart/form-data`\n- The request consists of three parts:\n 1. `request` (JSON): Contains\ \ claim metadata\n 2. `files` (binary): One or more attachment files (1-10 files)\n 3. `fileMetadata`\ \ (JSON): **Required for Image Intelligence** service information for the documents being uploaded\ \ as attachments. \n\n In order to enable Optum Image Intelligence on the attachments, each file\ \ MUST match fileName and mimeType as defined in the metadata object. \n- `procedureCodes`: Comma-separated\ \ list of alphanumeric procedure codes (max 25 chars each). Pattern: `([a-zA-Z0-9]{1,25})(,[a-zA-Z0-9]{1,25})`\ \ \n- `serviceDate`: Date in YYYY-MM-DD format. Pattern: `\\\\d{4}-\\\\d{2}-\\\\d{2}`\n- `toothNumbers`:\ \ Comma-separated list of tooth identifiers. Image Intelligence will further validate these values\ \ to numerical values. Pattern: `[A-Za-z0-9]{2}(,[A-Za-z0-9]{2})` \n\n**Example Request:**\n```\n\ --boundary\nContent-Disposition: form-data; name=\\\"request\\\"\nContent-Type: application/json\n\ \n{\n \\\"claimId\\\": \\\"CLM-2024-001234\\\",\n \\\"payerId\\\": \\\"ABC12\\\",\n \\\"providerNPI\\\ \": \\\"1234567890\\\",\n \\\"dateOfService\\\": \\\"2024-01-15\\\",\n \\\"patientLastName\\\ \": \\\"Atreides\\\",\n \\\"patientFirstName\\\": \\\"Paul\\\",\n \\\"patientDateOfBirth\\\"\ : \\\"2000-01-01\\\",\n \\\"memberId\\\": \\\"44444444\\\"\n}\n\n--boundary\nContent-Disposition:\ \ form-data; name=\\\"fileMetadata\\\"\nContent-Type: application/json\n\n[ \n {\n \\\"fileName\\\ \": \\\"xray_image.pdf\\\",\n \\\"mimeType\\\": \\\"application/pdf\\\",\n \\\"dateOfService\\\ \": \\\"2026-01-01\\\",\n \\\"procedureCodes\\\": \\\"D0101\\\",\n \\\"toothNumbers\\\": \\\"\ 14, 16\\\"\n }\n]\n\n--boundary\nContent-Disposition: form-data; name=\\\"files\\\"; filename=\\\ \"xray_image.pdf\\\"; \nContent-Type: application/pdf\n\n[binary file content]\n\n--boundary--\n\ ```\n\n**Supported File Types:** BMP, JPG/JPEG, TIFF, PNG, PDF, TXT, DOC/DOCX, DICOM, GIF, RTF\n\ \n**File Limits:** 1-10 files per request." operationId: createAttachmentsImageIntel requestBody: content: multipart/form-data: schema: type: object required: - submitterId - billingProviderTaxId - claimId - payerId - providerNPI - dateOfService - patientLastName - patientFirstName - patientDateOfBirth - memberId - fileMetadata - files properties: files: type: array items: type: string format: binary maxItems: 10 minItems: 1 description: Raw binary of the files to be uploaded as attachments claimId: type: string maxLength: 50 description: JSON property of request body property 'request' containing the claim ID associated with the attachments payerId: type: string pattern: ^[A-Za-z0-9]{5}$ description: JSON property of request body property 'request' containing the payer Id associated with the attachments memberId: type: string maxLength: 50 providerNPI: type: string pattern: ^[0-9]{10}$ description: JSON property of request body property 'request' containing the provider NPI associated with the attachments submitterId: type: string maxLength: 50 description: JSON property of request body property 'request' containing the submitter Id associated with the attachments. Requestor MUST have access to this submitter id. fileMetadata: type: array items: $ref: '#/components/schemas/ImageIntelligenceMetadata' dateOfService: type: string format: date description: JSON property of request body property 'request' containing the first Date of Service associated with the attachments patientLastName: type: string maxLength: 75 patientFirstName: type: string maxLength: 50 patientDateOfBirth: type: string maxLength: 10 billingProviderTaxId: type: string maxLength: 50 description: JSON property of request body property 'request' containing the billing provider tax Id associated with the attachments. Requestor MUST have access to this billing provider tax id (TIN). encoding: files: contentType: application/octet-stream, image/bmp, image/x-ms-bmp, image/jpeg, image/pjpeg, image/tiff, image/x-tiff, image/png, application/pdf, text/plain, text/x-text, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/dicom, application/dicom+json, application/dicom+xml, image/gif, application/rtf, text,rtf request: contentType: application/json required: true security: - bearerAuth: [] components: schemas: ErrorResponse: type: object properties: type: type: string format: uri default: about/blank example: https://api-stg.uhg.com/errors/attachment-type-detection description: The problem type URI. Defaults to `about:blank`. title: type: string example: Invalid Attachment Format description: A short, human-readable summary of the problem. detail: type: string example: The provided attachment format is not supported. description: A detailed explanation of the problem. status: type: integer format: int32 example: 400 maximum: 599 minimum: 100 description: The HTTP status code for the problem. instance: type: string format: uri example: https://api-stg.uhg.com/errors/attachment-type-detection/12345 description: A URI reference that identifies the specific occurrence of the problem. properties: type: object properties: errors: type: array items: type: object properties: code: type: string example: DENTATT_113 description: A code that can be correlated to this error. field: type: string example: DataService.attachments.find.notFound description: The field in a request that is related to this error, if applicable. message: type: string example: Attachment not found. description: A human readable message that describes the error. description: A collection that gives specifics about the errors that occurred. description: A map of additional, non-standard properties. description: Representation for an RFC 9457 problem detail. AttachmentData: type: object required: - attachmentId - fileName - mimeType - content properties: content: type: string format: byte example: JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL01lZGlhQm94IFswIDAgNjEyIDc5Ml0KL0NvbnRlbnRzIDQgMCBSCi9SZXNvdXJjZXMgPDwvUHJvY1NldCBbL1BERiAvVGV4dF0KL0ZvbnQgPDwvRjEgNiAwIFI+Pgo+Pgo+PgplbmRvYmoKNCAwIG9iago8PC9MZW5ndGggNDQ+PgpzdHJlYW0KQlQKL0YxIDI0IFRmCjEwMCA3MDAgVGQKKERlbnRhbCBYLVJheSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago= description: Base64 encoded file content fileName: type: string example: bitewing.png description: Original filename mimeType: type: string example: image/png description: MIME type of the original file attachmentId: type: string example: CHC#023981023345 pattern: ^[A-Z]{3}#[0-9]{12}$ description: Optum Real identifier of the attachment MemberMetadata: type: object properties: memberId: type: string patientLastName: type: string patientFirstName: type: string patientDateOfBirth: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ AttachmentStatus: type: object properties: fileId: type: string format: uuid mimeType: type: string attachmentId: type: string example: CHC#023981023345 pattern: ^[A-Z]{3}#[0-9]{12}$ fileSizeInBytes: type: integer format: int64 dateProcessedUtc: type: string format: date-time dateSubmittedUtc: type: string format: date-time originalFileName: type: string AttachmentMetadata: type: object required: - attachmentId - fileId - originalFileName - fileSizeInBytes - mimeType properties: tags: type: object example: serviceDate: '2026-01-15' attachmentId: 023981023345 toothNumbers: 14,23,24 procedureCodes: D0120,D0150 attachmentControlNumber: 507f1f77bcf86cd799439011 description: Map of user/system defined tags associated with the attachment additionalProperties: type: string fileId: type: string format: uuid payerId: type: string mimeType: type: string submitterId: type: string attachmentId: type: string example: CHC#023981023345 pattern: ^[A-Z]{3}#[0-9]{12}$ fileSizeInBytes: type: integer format: int64 dateProcessedUtc: type: string format: date-time dateSubmittedUtc: type: string format: date-time originalFileName: type: string billingProviderTaxId: type: string AttachmentStatusResponse: type: object required: - attachmentControlNumber - containerStatus - lastUpdatedBy - lastUpdatedUtc - attachments properties: attachments: type: array items: $ref: '#/components/schemas/AttachmentStatus' lastUpdatedBy: type: string example: exampleuser@optum.com lastUpdatedUtc: type: string format: date-time containerStatus: enum: - CREATED - ACTIVE - CLOSED - ARCHIVED type: string attachmentControlNumber: type: string example: CHC#507f1f77bcf86cd799439011 pattern: ^[A-Z]{3}#[0-9a-fA-F]{24}$ AttachmentUploadResponse: type: object required: - attachmentControlNumber - attachmentId - fileName - fileSizeInBytes - mimeType - uploadedAtUtc properties: fileName: type: string example: bitewing.png description: Original filename mimeType: type: string example: image/png attachmentId: type: string example: CHC#023981023345 pattern: ^[A-Z]{3}#[0-9]{12}$ uploadedAtUtc: type: string format: date-time fileSizeInBytes: type: integer format: int64 attachmentControlNumber: type: string example: CHC#507f1f77bcf86cd799439011 pattern: ^[A-Z]{3}#[0-9a-fA-F]{24}$ CreateAttachmentResponse: type: object required: - attachmentControlNumber - attachmentIds - status - createdAt properties: status: enum: - CREATED - ACTIVE - CLOSED - ARCHIVED type: string claimId: type: string createdAt: type: string format: date-time attachmentIds: type: array items: type: string example: CHC#023981023345 pattern: ^[A-Z]{3}#[0-9]{12}$ attachmentControlNumber: type: string example: CHC#507f1f77bcf86cd799439011 pattern: ^[A-Z]{3}#[0-9a-fA-F]{24}$ imageIntelligenceTransactionId: type: string description: If the request included image intelligence metadata and the files were successfully processed by Optum Image Intelligence, this field will be populated with the transaction id for reference AttachmentDetailsResponse: type: object required: - attachmentControlNumber - status properties: status: enum: - CREATED - ACTIVE - CLOSED - ARCHIVED type: string claimId: type: string attachments: type: array items: $ref: '#/components/schemas/AttachmentMetadata' providerNPI: type: string pattern: ^[0-9]{10}$ lastUpdatedBy: type: string example: user@optum.com lastUpdatedUtc: type: string format: date-time memberMetadata: $ref: '#/components/schemas/MemberMetadata' attachmentControlNumber: type: string example: CHC#507f1f77bcf86cd799439011 pattern: ^[A-Z]{3}#[0-9a-fA-F]{24}$ description: Unique identifier for the attachment container that attachments are associated with. This is used to group multiple attachments together under one container and associate with claim metadata prior to submission to payer. imageIntelligenceTransactionId: type: string format: uuid description: If any of the attachments associated with this container included image intelligence metadata and were successfully processed by Optum Image Intelligence, this field will be populated with the transaction id for reference ImageIntelligenceMetadata: type: object required: - fileName - mimeType - procedureCodes - serviceDate - toothNumbers properties: fileName: type: string example: xray_image.pdf description: Original filename of the attachment file being uploaded. This is used for reference in Optum Image Intelligence processing and is not required to match the actual filename of the uploaded file. mimeType: type: string example: application/pdf description: MIME type of the attachment file being uploaded. This is used for reference in Optum Image Intelligence processing and is not required to match the actual MIME type of the uploaded file. serviceDate: type: string pattern: ^\\d{4}-\\d{2}-\\d{2}$ description: Service date associated with the attachment in YYYY-MM-DD format. This is used for reference in Optum Image Intelligence processing. toothNumbers: type: string example: 12, 14, 08 pattern: ^[A-Za-z0-9]{2}(,[A-Za-z0-9]{2}) description: List of tooth numbers associated with the attachment. These are used for reference in Optum Image Intelligence processing and will be further validated to ensure they conform to valid tooth identifiers. procedureCodes: type: string example: D0120,D0150 pattern: ^([a-zA-Z0-9]{1,25})(,[a-zA-Z0-9]{1,25})$ description: List of procedure codes associated with the attachment. These are used for reference in Optum Image Intelligence processing. CompleteAttachmentsRequest: type: object required: - claimId - attachmentControlNumber properties: claimId: type: string maxLength: 50 memberId: type: string maxLength: 50 patientLastName: type: string maxLength: 75 patientFirstName: type: string maxLength: 50 patientDateOfBirth: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ attachmentControlNumber: type: string example: CHC#507f1f77bcf86cd799439011 pattern: ^[A-Z]{3}#[0-9a-fA-F]{24}$ GetAttachmentsJsonResponse: type: object required: - attachmentControlNumber - totalAttachments - attachments - memberMetadata properties: attachments: type: array items: $ref: '#/components/schemas/AttachmentData' description: List of attachments with base64 encoded content memberMetadata: $ref: '#/components/schemas/MemberMetadata' totalAttachments: type: integer format: int32 example: 1 description: Total number of attachments bound in the container represented by the attachment control number. This may be greater than the number of attachments returned in this response if an individual attachment Id is provided in the request. attachmentControlNumber: type: string pattern: ^[A-Z]{3}#[0-9a-fA-F]{24}$ description: Control number representing the the attachment transaction parameters: IdPath: in: path name: id schema: type: string pattern: ^([A-Z]{3}#)?([0-9]{12}|[0-9a-fA-F]{24})$ examples: attachmentId: value: 023981023345 summary: Attachment Id (references a single attachment) prefixedAttachmentId: value: CHC#023981023345 summary: Attachment Id (references a single attachment) - Prefixed attachmentControlNumber: value: 507f1f77bcf86cd799439011 summary: Attachment Control Number (references multiple attachments under one container) prefixedAttachmentControlNumber: value: CHC#507f1f77bcf86cd799439011 summary: Attachment Control Number (references multiple attachments under one container) - Prefixed required: true description: A valid Optum Real Attachment Id or Attachment Control Number as received by a Payer, optionally with the source system identifier and delimiter ClaimIdPath: in: path name: claimId schema: type: string maxLength: 50 required: true description: A valid Optum Real Claim Id associated with the attachments AttachmentIdPath: in: path name: attachmentId schema: type: string pattern: ^([A-Z]{3}#)?[0-9]{12}$ examples: attachmentId: value: '123204933756' summary: Attachment Id without source system prefix (references a single attachment) prefixedAttachmentId: value: CHC#123204933756 summary: Attachment Id with source system prefix (references a single attachment) required: true description: A valid Optum Real Attachment Id referring to an individual attachment uploaded by a Provider. AttachmentControlNumberPath: in: path name: attachmentControlNumber schema: type: string pattern: ^([A-Z]{3}#)?[0-9a-fA-F]{24}$ examples: attachmentControlNumber: value: 507f1f77bcf86cd799439011 summary: Attachment Control Number without source system prefix (references multiple attachments under one container) prefixedAttachmentControlNumber: value: CHC#507f1f77bcf86cd799439011 summary: Attachment Control Number with source system prefix (references multiple attachments under one container) required: true description: A valid Optum Real Attachment Control Number referring to multiple attachments uploaded by a Provider. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Enter a Bearer access token. The API Explorer applies the Bearer scheme. security: - bearerAuth: [] x-readme: explorer-enabled: true proxy-enabled: true