CourtAnalyticsTX - CMS Vendor API Documentation

About this Document

This guide contains the information needed to integrate with the pipeline to publish to CourtAnalyticsTX.

Terms

API Overview

Purpose and Business Value

The pipeline API allows Texas Courts to submit and manage large volumes of entity data for processing through CourtAnalyticsTX. The API automates mandatory state reporting processes across all Texas courts, reducing the need for manual data compilation and submission tasks. This digital infrastructure ensures compliance through automated validation, while improving data quality and consistency across all 254 counties with real-time error detection and standardized data schemas.

Required Prerequisites

• API Credentials: Valid client ID and client secret from CourtAnalyticsTX
• Network Access: Whitelist pipeline API endpoints in any firewall between the local CMS and CourtAnalyticsTX
• Data Preparation: Entity data formatted according to CourtAnalyticsTX schemas
• HTTPS Support: HTTPS-enabled client for secure communication
• Rate Limiting: Understand pipeline API rate limits and throttling policies

Environments

Network and Security Requirements

• APIs are accessible on the public internet and only support HTTPS traffic.
• Integrators must obtain credentials from CourtAnalyticsTX.
• Credentials will be used to request a bearer token from the CourtAnalyticsTX pipeline OAuth server.
• The bearer token must be included with each submission.

Getting Started

Step 1: Request Credentials

Utilize the Tyler Customer Portal Guide to submit the following ticket:

Product Suite:  Enterprise Justice Suite
Product Group: eFile & Serve
Product Module: Analytics
Program: TX Stage
Case Title: Credentials Request
Description: Provide publisher Client ID and Client Secret for data submission to the stage pipeline

Step 2: Get Access Token

Use Client ID and Client Secret to request a bearer token from the pipeline:

Endpoint: https://tyler-alliance-system-demo.auth-fips.us-gov-west-1.amazoncognito.com/oauth2/token

Method: POST

Example cURL:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --user YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
  -d "grant_type=client_credentials" \
  https://tyler-alliance-system-demo.auth-fips.us-gov-west-1.amazoncognito.com/oauth2/token

Access Token Expiration and Renewal

Access Tokens expire after 60 minutes. It is recommend to cache the token and refresh it within 5 minutes of expiration. Failure to renew the Access Token will result in 401 (Unauthorized) responses.

Step 3: Use Bearer Token to Submit Envelope

Every message consists of a single Envelope. The Envelope contains a series of events, as well as metadata to help route the message appropriately. An example message might look like:

Endpoint: https://api.test-alliance.tylerhost.net/exchange/Messages
Method: PUT

{
    "ResolveMappings": false,
    "ValidateEnvelope": true,
    "SynchronousValidation": true,
    "TriggeredBy": "Postman",
    "Events": [
        {
          "EventType": "di-texas-oca-new-record-event",
          "Entities": [
            {
              "EntityType": "di-texas-oca-court-case-events",
              "EntityId": "TX - OCA",
              "LinkEntity": false,
              "EntityData": {
                  "recordid": "[CREATE_UNIQUE_RECORD_ID]",
                  "county": "[ENTER_SUBMISSION_COUNTY]",
                  "publisher": "[ENTER_VENDOR_NAME]",
                }
              }
            ]
        }
    ]
}

Success Response

{
  "status": "SUCCESS",
  "EnvelopeId": "a0b5c31d-0643-4af3-b1af-f7799fa21e8d"
}

Error Response (Invalid Credentials)

{
  "error": "invalid_client"
}

👉 Note: This example uses the criminal sanctions schema as a template. Adjustments may be needed based on the case type/program area to which data is being submitted. This represents a minimal submission, with a single event containing a single entity, and only including the critical data elements for the entity schema.

Authentication Errors

To resolve:

• Validate that the submission URL is correct. This should be submitted to the authorization endpoint, NOT the message endpoint.
• Validate that the POST method is being used to submit the request.
• Validate that the client id is correct.
• Validate that the client secret is correct.

Submitting Data

Endpoint

PUT https://api.test-alliance.tylerhost.net/exchange/Messages

Purpose: Submit case-level data to the CourtAnalyticsTX staging pipeline for processing and validation.

Critical Parameters

Details for each attribute of the Envelope are:

Events

Envelopes may consist of one or more events. Details for each attribute of the Event are:

Entities

Entities specify the record and the values associated with that record. Each event contains at least one entity and can contain up to 50 entities. Details for each attribute are as follows:

Entity Types

EntityTypes map the record to a specific program and dataset. The following EntityType values are available:

- di-texas-oca-court-appointments
- di-texas-oca-court-attorney
- di-texas-oca-court-case-events
- di-texas-oca-court-case-status
- di-texas-oca-court-charges
- di-texas-oca-court-dispositions-criminal
- di-texas-oca-court-dispositions-non-criminal
- di-texas-oca-court-party

👉 Note: Entity types are subject to change as data schemas are finalized.

Entity Data

Every EntityData object must contain the elements, in the format required, listed in the data element schemas. The most recent version of the schemas can be found here: Case Level Data Schema

These should be passed as attributes in the object. For example:

{
  "Entities": [
    {
      "EntityType": "di-texas-oca-court-case-events",
      "EntityId": "TX - OCA",
      "LinkEntity": false,
      "EntityData": {
        "cause_number": "1234",
        "recordid": "a123b456-cd78-90ef-gh10-11i12j13k",
        "county": "Dallas",
        "publisher": "Publisher-Name",
        "court_id_number": "123456789",
        "primary_case_category": "Criminal",
        "case_type": "Misdemeanor",
        "charge_number": "1",
        "judicial_council_case_type": "Other Misdemeanors",
        "sentence_type": "Probation/Community Supervision",
        "sentencing_date": "2025-01-01",
        "monetary_penalty_amount": null
      }
    ]
  }

There are a couple of critical items when building the EntityData object:

• Data Elements: Each Entity must include the required elements listed in the schema, in the format specified. The format must be consistent with the Regular Expression patterns specified.
• Record ID: The Record ID is used to allow the vendor to maintain (modify, update, delete) the data after it’s been submitted. This is a unique identifier for the object in the local case management system. Each object must have a unique Record ID.

Submit a New Record

Sample Request

Endpoint: https://api.test-alliance.tylerhost.net/exchange/Messages
Method: PUT

{
    "ResolveMappings": false,
    "ValidateEnvelope": true,
    "SynchronousValidation": true,
    "TriggeredBy": "Postman",
    "Events": [
        {
            "EventType": "di-texas-oca-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-texas-oca-court-case-events",
                    "EntityId": "TX - OCA",
                    "LinkEntity": false,
                    "EntityData": {
                        "cause_number": "12-345-ABCD-12345",
                        "recordid": "[CREATE_UNIQUE_RECORD_ID]",
                        "county": "[ENTER_SUBMISSION_COUNTY]",
                        "publisher": "[ENTER_VENDOR_NAME]",
                        "court_id_number": "123456789",
                        "primary_case_category": "Criminal",
                        "case_type": "Felony",
                        "charge_number": "1",
                        "judicial_council_case_type": "Aggravated Assault or Attempted Murder",
                        "sentence_type": "Confinement - Prison",
                        "sentencing_date": "2025-01-01",
                        "concurrent_consecutive_sentence": null,
                        "monetary_penalty_amount": null
                    }
                }
            ]
        }
    ]
}

Sample Response

{
    "status": "SUCCESS",
    "EnvelopeId": "a0b5c31d-0643-4af3-b1af-f7799fa21e8d"
}

Update an Existing Record

If the values of an existing record require correction or augmentation, this can be accomplished using the same di-texas-oca-new-record-event EventType employed for the submission of new records. The distinction lies in the necessity to specify only the Record ID and County of the record that requires correction or augmentation. The fields specified in EntityData, and only those fields, will have their values updated. Other fields, and their values (if applicable), will remain unaffected.

In the following example, it is important to note that only the specified fields are modified, while the others remain unchanged. The system identifies an existing record with the specified Record ID-County combination from the earlier example. In summary: The only field that changes after the following submissions is the event’s sentencing_date, which was previously 2025-01-01 and will now be 2020-01-01. This demonstrates how to edit the value of a specific field in a record.

Endpoint: https://api.test-alliance.tylerhost.net/exchange/Messages
Method: PUT

{
    "ResolveMappings": false,
    "ValidateEnvelope": true,
    "SynchronousValidation": true,
    "TriggeredBy": "Postman",
    "Events": [
        {
            "EventType": "di-texas-oca-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-texas-oca-court-case-events",
                    "EntityId": "TX - OCA",
                    "LinkEntity": false,
                    "EntityData": {
                        "cause_number": "12-345-ABCD-12345",
                        "recordid": "[CREATE_UNIQUE_RECORD_ID]",
                        "county": "[ENTER_SUBMISSION_COUNTY]",
                        "publisher": "[ENTER_VENDOR_NAME]",
                        "court_id_number": "123456789",
                        "primary_case_category": "Criminal",
                        "case_type": "Felony",
                        "charge_number": "1",
                        "judicial_council_case_type": "Aggravated Assault or Attempted Murder",
                        "sentence_type": "Confinement - Prison",
                        "sentencing_date": "2020-01-01",
                        "concurrent_consecutive_sentence": null,
                        "monetary_penalty_amount": null
                    }
                }
            ]
        }
    ]
}

Delete an Existing Record

In the event of an erroneous record or an expunged record, it can be deleted from CourtAnalyticsTX using the combination of the Record ID and County so that the system is able to identify the correct row to delete.

Here is an example. Note that the EventType for di-texas-oca-delete-record-event is used, and the record is referred to by its Record ID and County.

Endpoint: https://api.test-alliance.tylerhost.net/exchange/Messages
Method: PUT

{
    "ResolveMappings": false,
    "ValidateEnvelope": true,
    "SynchronousValidation": true,
    "TriggeredBy": "Postman",
    "Events": [
        {
            "EventType": "di-texas-oca-delete-record-event",
            "Entities": [
                {
                    "EntityType": "di-texas-oca-court-criminal-sanctions",
                    "EntityId": "TX - OCA",
                    "LinkEntity": false,
                    "EntityData": {
                        "recordid": "[ENTER_SAME_RECORD_ID_AS_RECORD_TO_DELETE]",
                        "publisher": "[ENTER_VENDOR_NAME]",
                        "county": "[ENTER_SUBMISSION_COUNTY]"
                    }
                }
            ]
        }
    ]
}

Nullify Specific Fields in a Record

To nullify a field in an existing record, the di-texas-oca-new-record-event EventType should be used, along with the appropriate Record ID, County, and publisher of the record to identify the specific row. The field(s) in EntityData whose values are to be nullified should then be specified. Submit null as the value for all data types to nullify the field.

In the example below, case_type (of type enum) and sentencing_date (of type date) are both being nullified.

{
    "ResolveMappings": false,
    "ValidateEnvelope": true,
    "SynchronousValidation": true,
    "TriggeredBy": "Postman",
    "Events": [
        {
            "EventType": "di-texas-oca-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-texas-oca-court-case-events",
                    "EntityId": "TX - OCA",
                    "LinkEntity": false,
                    "EntityData": {
                        "cause_number": "12-345-ABCD-12345",
                        "recordid": "[CREATE_UNIQUE_RECORD_ID]",
                        "county": "[ENTER_SUBMISSION_COUNTY]",
                        "publisher": "[ENTER_VENDOR_NAME]",
                        "court_id_number": "123456789",
                        "primary_case_category": "Criminal",
                        "case_type": null,
                        "charge_number": "1",
                        "judicial_council_case_type": "Aggravated Assault or Attempted Murder",
                        "sentence_type": "Confinement - Prison",
                        "sentencing_date": null,
                        "concurrent_consecutive_sentence": null,
                        "monetary_penalty_amount": null
                    }
                }
            ]
        }
    ]
}

Data Schemas and Validation

The following limits are in place for all envelope submissions:

Nesting Structure Examples

Multiple Entities Within One Event

When nesting multiple entities within a single event, follow this structure:

{
  "ResolveMappings": false,
  "ValidateEnvelope": true,
  "SynchronousValidation": true,
  "TriggeredBy": "Postman",
  "Events": [
    {
      "EventType": "di-texas-oca-new-record-event",
      "Entities": [
        {
          "EntityType": "di-texas-oca-court-case-events",
          "EntityId": "TX - OCA",
          "LinkEntity": false,
          "EntityData": {
            "recordid": "test1",
            "publisher": "[PUBLISHER NAME HERE]",
            "county": "Anderson"
          }
        },
        {
          "EntityType": "di-texas-oca-court-case-events",
          "EntityId": "TX - OCA",
          "LinkEntity": false,
          "EntityData": {
            "recordid": "test2",
            "publisher": "[PUBLISHER NAME HERE]",
            "county": "Anderson"
          }
        }
        // ...Continue adding entities until you hit the 50 entity maximum per event
      ]
    }
  ]
}

Nesting Events Within One Envelope

{
  "ResolveMappings": false,
  "ValidateEnvelope": true,
  "SynchronousValidation": true,
  "TriggeredBy": "Postman",
  "Events": [
    {
      "EventType": "di-texas-oca-new-record-event",
      "Entities": [
        {
          "EntityType": "di-texas-oca-court-case-events",
          "EntityId": "TX - OCA",
          "LinkEntity": false,
          "EntityData": {
            "recordid": "test1",
            "publisher": "[PUBLISHER NAME HERE]",
            "county": "Anderson"
          }
        },
        {
          "EntityType": "di-texas-oca-court-case-events",
          "EntityId": "TX - OCA",
          "LinkEntity": false,
          "EntityData": {
            "recordid": "test2",
            "publisher": "[PUBLISHER NAME HERE]",
            "county": "Anderson"
          }
        }
        // ...Continue adding entities until you hit the 50 entity maximum per event
      ]
    },
    {
      "EventType": "di-texas-oca-new-record-event",
      "Entities": [
        {
          "EntityType": "di-texas-oca-court-case-events",
          "EntityId": "TX - OCA",
          "LinkEntity": false,
          "EntityData": {
            "recordid": "test3",
            "publisher": "[PUBLISHER NAME HERE]",
            "county": "Anderson"
          }
        },
        {
          "EntityType": "di-texas-oca-court-case-events",
          "EntityId": "TX - OCA",
          "LinkEntity": false,
          "EntityData": {
            "recordid": "test4",
            "publisher": "[PUBLISHER NAME HERE]",
            "county": "Anderson"
          }
        }
        // ...Continue adding entities until you hit the 50 entity maximum per event
      ]
    }
    // ...Continue adding events until you hit the 50 event maximum per envelope
  ]
}

Important IDs to Track

The pipeline utilizes three pieces of information to uniquely identify a record: the Record ID, the County, and the Publisher. It is necessary to track two of these: the Record ID and County. Both will be required to edit and delete records at a later stage. It is also highly recommended to retain the Envelope ID for each submission, as described below.

Partial Records

All Critical and Required elements available should be included when submitting records. While only the critical elements are technically required to submit data to the pipeline, the data can only support the state reporting requirements if required elements are also included in the submissions. Integrations that fail to consistently provide required and critical data elements will not be approved for production.

Spaces and Capitalization

The Data Elements that are categorical in nature undergo rigorous validation against finite, predefined sets of enumerated values. These values are listed in the Data Elements for the applicable variables. For these elements, it is imperative to ensure that the values provided match one of the enumerated values precisely, with no differences in spacing and the same casing of letters. For example,

"primary_case_category": "Probate and Guardianship"

is valid, but

"primary_case_category": "probate and guardianship"

is not. In the Excel version of the schema, these values are listed in the ‘Values’ column of the workbook. In the JSON data contracts, the values are listed in the following structure:

"enum": [
  "Criminal",
  "Civil",
  "Juvenile",
  "Family",
  "Probate and Guardianship",
  "Mental Health", 
  null
]

Data Formats and Enumerations

Event Types

• “di-texas-oca-new-record-event”
• “di-texas-oca-delete-record-event”

Entity Types

• “di-texas-oca-court-appointments”
• “di-texas-oca-court-attorney”
• “di-texas-oca-court-case-events”
• “di-texas-oca-court-case-status”
• “di-texas-oca-court-charges”
• “di-texas-oca-court-dispositions-criminal”
• “di-texas-oca-court-dispositions-non_criminal”
• “di-texas-oca-court-party”

Date Format

All dates must be in ISO 8601 format: YYYY-MM-DD

Error Handling and Response Codes

Synchronous Error Validation

To utilize synchronous error validation, the flag should be set to “true” in the submission JSON ( “SynchronousValidation”: true,), as demonstrated in all examples contained in this document. Enabling this feature ensures that errors for data submissions are returned directly in the API response to the data submission. If this flag is set to false, synchronous errors will not be processed slowing down development.

HTTP Status Codes

Error Response Structure

Start by consulting the information below. If additional help is needed, utilize the Tyler Customer Portal Guide to submit a ticket including all relevant information discussed in the guide e.g. message traffic, error messages, steps to reproduce, and steps already taken to resolve.

Reminders

• When submitting records, make sure to use PUT instead of POST
• Remember that Bearer Tokens expire after One Hour

Common Validation Errors

The Court Analytics Texas requires that all Pipeline Critical Elements be included. If one or more Pipeline Critical Elements are missing from the submission, an error will be received. It should be noted that an error indicating ‘required’ refers to an error with Pipeline Critical Elements.

keyword: required
dataPath: 
schemaPath: #/required
message: should have required property 'recordid'
Message: Contract Schema Failed Validation.
ErrorSchema: di-texas-oca-court-case-events
Fix: Provide the Pipeline Critical Elements and resend message

Keyword Pattern

Critical elements undergo pattern matching to test the contents of the element’s string value. The pipeline validates the data by checking for a pattern within the string against RegEx for the expected date format. If that pattern is not met, an error will be received.

keyword: pattern
dataPath: .status_date
schemaPath: #/properties/status_date/pattern
message: should match pattern "^(0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])[- /.](19|20)\d\d$"
Message: Contract Schema Failed Validation.
ErrorSchema: di-texas-oca-court-case-events

Fix: Check the contents of the status_date (or equivalent) element and confirm that the submission matches the expected contents. In the example above, it tests that contents match a date format similar to the YYYY-MM-DD format.

Additional Properties

There is a column in the submission that is not listed in the data elements.

keyword: additionalProperties
dataPath:
schemaPath: #/additionalProperties
message: should NOT have additional properties
Message: Contract Schema Failed Validation.

Fix: Remove any elements from the submission that are not included in the data elements. Note that sometimes the error will not state which elements are extra.

Field Validation Errors: Type

Non-critical elements must have correct JSON formatting to either be a number or string. If the data element should be a number, it should not be formatted as a string.

keyword: type
dataPath: .eventdate
schemaPath: #/properties/dateofbirth/type
message: should be string
Message: Contract Schema Failed Validation.
ErrorSchema: di-texas-oca-court-case-events screeninghttps://socrata.atlassian.net/plugins/servlet/ac/com.ricksoft-inc.plugins.space-sync-for-confluence/com.ricksoft-inc.plugins.space-sync-for-confluence__mention-users-in-synced-site?page.id=2571796685&space.key=SD&content.id=2571796685&content.version=56&page.type=page&page.title=OCA%20Staging%3A%20Instruction%20Steps%20and%20FAQs%20%20DRAFT_v1.1&space.id=384172439&content.type=page&user.isExternalCollaborator=false&page.version=56

Fix: Ensure the dateofbirth is a string, formatted as YYYY-MM-DD.

Categorical Variable Enumeration

An error with a keyword of enum means that the variable’s value needs to equal one of a finite list of values.

keyword: enum
dataPath: .initialacute2007override
schemaPath: #/properties/initialacute2007override/enum
message: should be equal to one of the allowed values
Message: Contract Schema Failed Validation.
ErrorSchema: di-texas-oca-court-case-events

Fix: Consult the Data Elements and make sure the value for this variable in the record is equal to one of the enumerated values.

Troubleshooting Steps

For Authentication Issues (401)

1. Verify client credentials are correct
2. Check if access token has expired (60-minute limit)
3. Validate token format and Bearer prefix

For Validation Errors (400/422)

1. Review error details for specific field issues
2. Verify all required fields are present
3. Check data formats match schema requirements
4. Validate business rules compliance

For Rate Limiting (429)

1. Implement exponential backoff retry logic
2. Monitor rate limit headers in responses
3. Consider batching requests to reduce frequency
4. Contact support for rate limit increases if needed

For Server Errors (500)

1. Retry request after brief delay
2. Check system status page for known issues
3. Contact technical support with request ID
4. Implement circuit breaker pattern for resilience