Technical Reference Guide

📘

NOTE

Please use the table of contents on the right side of this page to quickly navigate to a desired section.

API Data dictionary

The following data dictionary includes all the essential information you will need to integrate with our Dental Attachments API and serves as a ready reference source should you encounter a problem. It is intended to support developers, analysts, and stakeholders in understanding the structure, usage, and expected values of the data exchanged through the system.

Use this data dictionary:

  • As a reference when integrating with or troubleshooting the API/data interface.
  • Ensure all required fields are populated when constructing requests.
  • Refer to the HTTP status codes section for guidance on resolving issues.

Query examples — See the following example queries or API requests that illustrate the usage and expected formats; useful for developers and testers to understand expected formats and usage patterns.

Request body — Defines the input parameters required for API calls or data queries. Includes field names, data types, required/optional status, and descriptions.

Parameters — Provide required and optional fields for the API calls.

Response body — Lists the fields returned in the response payload. Includes field names, data types, formats, and descriptions.

📘

NOTE

Please note that our APIs are private and secure, and require unique credentials to generate a Bearer token and gain access to. Please see (generate a Bearer token based on your API environment) to obtain access to our APIs.

URLs

SandboxProduction
Generate Bearer token — https://sandbox-apigw.optum.com/apip/auth/sntl/v1/tokenGenerate Bearer token — https://apigw.optum.com/apip/auth/sntl/v1/token
Health check — https://sandbox-apigw.optum.com/dental/attachments/v1/healthcheckHealth check — https://apigw.optum.com/dental/attachments/v1/healthcheck
Create Attachments by Uploading Documents — https://sandbox-apigw.optum.com/dental/attachments/v1/attachments/documentsCreate Attachments by Uploading Documents — https://apigw.optum.com/dental/attachments/v1/documents
Search for Attachments by IDs — https://sandbox-apigw.optum.com/dental/attachments/v1/attachments/documents/searchSearch for Attachments by IDs — https://apigw.optum.com/dental/attachments/v1/attachments/documents/search
Create Attachments by Uploading Documents and Enabling Image Intelligence — https://sandbox-apigw.optum.com/dental/attachments/v1/attachments/documents/image-intelligenceCreate Attachments by Uploading Documents and Enabling Image Intelligence — https://apigw.optum.com/dental/attachments/v1/attachments/documents/image-intelligence

Generate a Bearer token

Click Generate Bearer Token for Optum Real Dental APIs, for steps, see Generate a Bearer Token.

Dental Attachments OpenAPI Spec

To download, click Dental Attachments OpenAPI spec.

Perform API health check

The /healthcheck endpoint verifies that the connection to the API server is established and the API is operational. Use your Bearer token to perform API health check.

📘

API TESTING/USING

  • In our developer portal TryIt! interface
    • You need to reapply the Bearer token within the Bearer token expiry span by entering it in the CREDENTIALS box to test/use different APIs.
  • In your development platform
    • The generated Bearer token need not be reapplied or re-entered to test/use different APIs; the same Bearer token will be used across all transactions during the full token lifespan, and you can automatically refresh the token just before it expires.

In the developer portal Try It! interface

  1. Paste the Bearer token (generated as mentioned above), in the CREDENTIALS >> Bearer box as mentioned in the Generate a Bearer token section above.
  2. Click Try It! under the cURL Request box.

If the request was successful, the response shows such as, {"message": "Service is healthy"} in the RESPONSE box to indicate that the APIs are operational and are accessible. If the request failed, the reason shows in the RESPONSE box as listed in the HTTP Status Codes section at the end of this page or click the link in the TOC on the right.

Note that each API health message depends on the API being tested/used.

In your development platform

  1. Download our OpenAPI Spec (for example, to access a product OpenAPI spec you are using/testing, go to the required API Overview section >> click Download OpenAPI Spec.) and import it into the API project in your development platform.
  2. Expand the API collection folder and click the Get Token endpoint to generate a Bearer token.
  3. Click the Body tab and enter your unique secure credentials.
    • grant_type: client_credentials
    • client_id: your client_id
    • client_secret: your client_secret
    1. Send the request to generate a Bearer token.
  4. Now, click the /healthcheck endpoint and send it view if the connection to the API server was established.

The Bearer token will be valid until the Bearer token expires to try the APIs.

If the request was successful, the response shows such as, {"message": "Service is healthy"} in the RESPONSE box to indicate that the APIs are operational and are accessible. If the request failed, the reason shows in the RESPONSE box as listed in the HTTP Status Codes section at the end of this page or click the link in the TOC on the right.

Note that each API health message depends on the API being tested/used.

For a list of status messages, see HTTP Status Codes.

Create Attachments by uploading documents

attachments/documents (link to Create Attachments API) — Providers can create Attachments by uploading the files with the 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.

👍

TIP

  1. Choose an option to test/use our APIs, that is, in our developer portal TryIt! interface (you need to copy and paste the unexpired Bearer token generated for testing the Healthcheck) and/or in your development platform.
  2. Repeat the steps provided in the Perform API Healthcheck >> In your developer platform or In our developer portal TryIt! interface section.
    You can use the example field values provided in the Parameters table).

📘

NOTE

Supported File Types: BMP, JPG/JPEG, TIFF, PNG, PDF, TXT, DOC/DOCX, DICOM, GIF, RTF

Supported Number of Files: 1-10 files per request

Parameters

ParameterIn Developer PortalIn Development PlatformDescription
files (required)Enter (example given below)Click the Body tab to enter (example given below)Raw binary of the files to be uploaded as attachments
claimId (required)EnterClick the Params tab to addClaim ID associated with the attachments
payerId (required)EnterClick the Params tab to addPayer ID associated with the attachments
memberId (required)EnterClick the Params tab to addID present on the insurance ID card
providerNPI (required)EnterClick the Params tab to addProvider NPI associated with the attachments
submitterId (required)EnterClick the Params tab to addSubmitter ID associated with the attachments; requestor MUST have access to this submitter ID
dateOfService (required)EnterClick the Params tab to addFirst Date of Service associated with the attachments
patientLastName (required)EnterClick the Params tab to addPatient's last name, for example, "Atreides"
patientFirstName (required)EnterClick the Params tab to addPatient's first name, for example, "Paul"
patientDateOfBirth (required)EnterClick the Params tab to addPatient's date of birth, for example, "2000-01-01"
billingProviderTaxId (required)EnterClick the Params tab to addBilling provider tax ID associated with the attachments; requestor MUST have access to this billing provider tax ID (TIN)

📘

NOTE

Check the Headers and Body parameters to make sure that the values comply with the parameters provided in the Parameters table.

Request format

  • Content-Type: multipart/form-data
  • The request consists of three parts:
    • request (JSON): Contains claim metadata
    • files(binary): One or more attachment files (1-10 files)
--boundary`
`Content-Disposition: form-data; name=\"request\"`
`Content-Type: application/json

{
	"claimId\": \"CLM-2024-001234\",
  "payerId\": \"ABC12\",
  "providerNPI\": \"1234567890\",
  "dateOfService\": \"2024-01-15\",
  "patientLastName\": \"Atreides\",
  "patientFirstName\": \"Paul\",
  "patientDateOfBirth\": \"2000-01-01\",
  "memberId\": \"44444444\"
}

--boundary  
Content-Disposition: form-data; name=\"files\"; filename=\"xray_image.pdf\";

Content-Type: application/pdf

[binary file content]

--boundary--

❗️

IMPORTANT

Please note that the request requires you to provide all the required field values. Please note that these required values are GREYED out, which are pre-populated example values and can be selected to view the canned response. To view the required fields, expand the + symbol (indicated by the variables field below.

If the request was successful, the response shows "200 Successful response" and the information (see the following example) shows in the RESPONSE box. If the request failed, the reason shows in the RESPONSE box as listed in the HTTP Status Codes section at the end of this page or click the HTTPS Status Codes hyperlink in the TOC on the right.

{
  "status": "CLOSED",
  "createdAt": "2024-01-15T14:30:00Z",
  "attachmentIds": [
    "CHC#123456789055"
  ],
  "attachmentControlNumber": "CHC#507f1f77bcf86cd799439011"
}

Search for Attachments by IDs

/documents/search (link to Search for Attachments by IDs API) — Payers can search for, retrieve, and download the original binary file with appropriate Content-Typeand Content-Disposition headers for all the requested Attachments by ID.

  1. Enter the attachment ID (created by performing the create attachments API).
  2. Click the + symbol to add 1 to 10 attachment IDs.
{
  "attachmentIds": [
    "CHC#123456789055",
    "CHC#123456358902",
    "CHC#122256789023"
  ]
}

Parameter

ParameterIn Developer PortalIn Development PlatformDescription
attachmentsIdsEnterClick the Body tab to addA valid Optum Real Attachment ID or Attachment Control Number as received by a payer.
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="xray_1.pdf"; attachmentControlNumber="507f1f77bcf86cd799439011"; attachmentId="023981023345"
Content-Type: application/pdf

[binary file content]
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="report_2.pdf"; attachmentControlNumber="507f1f77bcf86cd799439011"; attachmentId="023981023346"
Content-Type: application/pdf

[binary file content]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Create Attachments by Uploading Documents and Enabling Image Intelligence

attachments/documents/image-intelligence (link to Create Attachments by uploading documents and enabling Image Intelligence API) — Endpoint creates Attachments by uploading the files with the 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.

👍

TIP

  1. Choose an option to test/use our APIs, that is, in our developer portal TryIt! interface (you need to copy and paste the unexpired Bearer token generated for testing the Healthcheck) and/or in your development platform.
  2. Repeat the steps provided in the Perform API Healthcheck >> In your developer platform or In our developer portal TryIt! interface section.
    You can use the example field values provided in the Parameters table).

Parameters

ParameterIn Developer PortalIn Development PlatformDescription
files (required)Enter or selectClick the Body tab to addRaw binary of the files to be uploaded as attachments
claimId (required)Enter or selectClick the Body tab to addClaim ID associated with the attachments
payerId (required)Enter or selectClick the Body tab to addPayer ID associated with the attachments
memberId (required)Enter or selectClick the Body tab to addID present on the insurance ID card
providerNPI (required)Enter or selectClick the Body tab to addProvider NPI associated with the attachments
submitterId (required)Enter or selectClick the Body tab to addSubmitter ID associated with the attachments; requestor MUST have access to this submitter ID
fileMetadata (required)Enter or selectClick the Body tab to addImage Intelligence metadata
dateOfService (required)Enter or selectClick the Body tab to addFirst Date of Service associated with the attachments
patientLastName (required)Enter or selectClick the Body tab to addPatient's last name, for example, "Atreides"
patientFirstName (required)Enter or selectClick the Body tab to addPatient's first name, for example, "Paul"
patientDateOfBirth (required)Enter or selectClick the Body tab to addPatient's date of birth, for example, "2000-01-01"
billingProviderTaxId (required)Enter or selectClick the Body tab to addBilling provider tax Id associated with the attachments; requestor MUST have access to this billing provider tax ID (TIN)
  • Content-Type: multipart/form-data
  • The request consists of three parts:
    • request (JSON): Contains claim metadata
    • files (Binary): One or more attachment files (1-10 files)
    • fileMetadata (JSON): Required for Image Intelligence service information for the documents being uploaded as attachments.

      📘

      NOTE

      To enable Optum Image Intelligence on the attachments, each file MUST match fileName and mimeType as defined in the metadata object.

    • 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})
    • serviceDate: Date in YYYY-MM-DD format. Pattern: \\d{4}-\\d{2}-\\d{2}
    • 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})
--boundary
Content-Disposition: form-data; name=\"request\"
Content-Type: application/json

{
  \"claimId\": \"CLM-2024-001234\",
  \"payerId\": \"ABC12\",
  \"providerNPI\": \"1234567890\",
  \"dateOfService\": \"2024-01-15\",
  \"patientLastName\": \"Atreides\",
  \"patientFirstName\": \"Paul\",
  \"patientDateOfBirth\": \"2000-01-01\",
  \"memberId\": \"44444444\"
}

--boundary
Content-Disposition: form-data; name=\"fileMetadata\"
Content-Type: application/json

[ 
 {
  \"fileName\": \"xray_image.pdf\",
  \"mimeType\": \"application/pdf\",
  \"dateOfService\": \"2026-01-01\",
  \"procedureCodes\": \"D0101\",
  \"toothNumbers\": \"14, 16\"
 }
]

--boundary
Content-Disposition: form-data; name=\"files\"; filename=\"xray_image.pdf\"; 
Content-Type: application/pdf

[binary file content]

--boundary--

📘

NOTE

Check the Headers and Body parameters to make sure that the values comply with the parameters provided in the Parameters table.

❗️

IMPORTANT

Please note that the request requires you to provide all the required field values. Please note that these required values are GREYED out, which are pre-populated example values and can be selected to view the canned response. To view the required fields, expand the + symbol (indicated by the variables field below.

If the request was successful, the response shows "200 Successful response" and the information (see the following example) shows in the RESPONSE box. If the request failed, the reason shows in the RESPONSE box as listed in the HTTP Status Codes section at the end of this page or click the HTTPS Status Codes hyperlink in the TOC on the right.

"status": "CLOSED",
"createdAt": "2024-01-15T14:30:00Z",
"attachmentIds": [
"CHC#123456789055"
],
"attachmentControlNumber": "CHC#507f1f77bcf86cd799439011",
"imageIntelligenceTransactionId": "69122940fab78c16744c5cc2"
}

👍

TIP

  1. Choose an option to test/use our APIs, that is, in our developer portal TryIt! interface (you need to copy and paste the unexpired Bearer token generated for testing the Healthcheck) and/or in your development platform.
  2. Repeat the steps provided in the Perform API Healthcheck >> In your developer platform or In our developer portal TryIt! interface section.
    You can use the example field values provided in the Parameters table).

API Setup

For information about, setting your API test environment, please see API Setup.

Subscribe to live and mock data testing in sandbox

Please see Subscribe to live and mock data testing in sandbox.

Integrate our APIs in your production environment

Please see Integrate our APIs in production environment.

HTTP status codes

Create Attachments

Create Attachments

Search Attachments

Search Attachments

Error Codes

📘

NOTE

Any error codes not listed in this document should be referred to customer support for assistance.

Default error: DENTATT_001 — An unexpected error prevents the completion of this request. Please try again. If the problem persists, please contact customer support.

General

Error CodeMessage
DENTATT_001An unexpected error prevents the completion of this request. Please try again. If the problem persists, please contact customer support.

Miscellaneous

Error CodeMessage
DENTATT_106Comprehensive attachment request timed out.
DENTATT_110Claim ID does not match the attachment's claim ID during completion.
DENTATT_111Requested attachment Ids are not associated.
DENTATT_112All member metadata fields must be provided if any are provided.
DENTATT_114Please contact customer support with this error code.
DENTATT_117The request could not be completed.
DENTATT_118The request could not be completed.
DENTATT_119The requested resource is unavailable.
DENTATT_120The request could not be completed.
DENTATT_121The request could not be completed.
DENTATT_122The request could not be processed.
DENTATT_180No files found in attachment.
DENTATT_181The request could not be completed.

Data Access

Error CodeMessage
DENTATT_201Attachment not found.
DENTATT_202The requested resource is unavailable.

User Access

Error CodeMessage
DENTATT_300Access Forbidden.
DENTATT_301Access Forbidden.
DENTATT_302Access Forbidden.
DENTATT_303User Authorization is empty.
DENTATT_305User identity is not recognized for the given payerId.
DENTATT_306Access Forbidden

Request Validation

Error CodeMessage
DENTATT_004Claim ID is required.
DENTATT_005Claim ID exceeds maximum length of 50 characters.
DENTATT_006Payer ID is required.
DENTATT_007Payer ID must be exactly 5 alphanumeric characters.
DENTATT_008Provider NPI is required.
DENTATT_009Provider NPI failed checksum validation.
DENTATT_010Provider NPI must be exactly 10 digits.
DENTATT_011Date of service is required.
DENTATT_012Date of service must be in YYYY-MM-DD or YYYYMMDD format.
DENTATT_013Patient date of birth must be in YYYY-MM-DD format.
DENTATT_014Patient last name does not match required pattern.
DENTATT_015Patient first name does not match required pattern.
DENTATT_016Member ID does not match required pattern.
DENTATT_017Attachment IDs list is required.
DENTATT_018Attachment ID must be either a 12-character hexadecimal string or prefixed format (XXX#xxxxxxxxxxxx).
DENTATT_020Submitter ID is required.
DENTATT_021Billing provider tax ID is required.
DENTATT_022Billing provider tax ID does not match required format.
DENTATT_023The request could not be processed.
DENTATT_539Date of service cannot be in the future.

❗️

ATTENTION

_TEST__ error codes are reserved for internal testing and are intentionally excluded from these tables.