Real-time (synchronous) coding

WoAG Occupation Coding Service User Guide

Single record and small batch coding.

Cite
Released
30/06/2025
Release date and time
30/06/2025 11:30am AEST

Single record coding

The coding service has been designed to apply a classification code and title to a free text entry. The synchronous single record coding feature will enable public facing webforms and other points of data collection to have codes and titles suggested in real time (~1 second). 

  • The service will provide multiple responses within a classification category, as long as at least one response has a confidence level above the threshold.
  • It may only provide one response - for example, if there is only one six-digit code in the relevant category.
  • If no responses are above the confidence threshold, the service will not return any results. 

Small batch coding

A small JSON file of up to 300 text records can also be coded synchronously. 

Note: when you are running a synchronous small batch, the whole packet needs to be syntactically correct. If the syntax fails, the whole batch will fail. As the operation is combined for the whole group of records, none of the records will be able to be coded if there is an error in any record.

When to use synchronous or asynchronous coding

Synchronous coding should only be used for single record coding or small batches of data. If you are coding 900 records, for example, it will be possible to run them in three small batch submissions.

Asynchronous large batch coding is recommended if you need to code or recode a large volume of data. (Large batch coding can be used to code from 1 record to millions of records.)

Coding against the latest model for a topic

This endpoint is used to code a single or small batch of free text records against the specified coding topic, using the latest model for that topic.

Request syntax

Depending on whether you are coding a single record or a small batch of records, your request will follow one of the following formats:

1. Coding a single free text record
POST /v1/topics/{topic}/code HTTP/1.1
Host: string 
Content-type: application/json
Authorization: string
{
    "record": {
        "occp_text": "string",
        "tasks_text": "string"
    },
    "numberOfSuggestions": number
}
2. Coding a small batch of free text records
POST /v1/topics/{topic}/code HTTP/1.1 
Host: string
Content-type: application/json
Authorization: string
{
    "records": [
        {
            "recordId": "string",
            "occp_text": "string",
            "tasks_text": "string"
        },
    ],
    "numberOfSuggestions": number
}

See Integration script examples for example PowerShell single record and small batch coding scripts.

URI request parameters
topicThe uriName of the topic against which the record is coded. This can be acquired by listing the available topics.
 Required: Yes
Request body
recordThe free text record to be coded.                                                                                                   
Type: Record object, following the input format specified by the model.
Required: No, but either record or records must be provided.
recordsThe free text records to be coded.
Type: Array of Record objects, following the input format specified by the model. Each item may optionally specify an additional string value recordId.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: No, but either record or records must be provided.
numberOfSuggestionsThe number of suggested codes to be provided if the record cannot be coded successfully. The maximum value of this field is 16.
Type: Number
Required: No

Response syntax

The response of this endpoint will depend on whether your input request contained a single record or a small batch of records.

1. Coding a single free text record
HTTP/1.1 200 OK
Content-type: application/json
{
    "codeStatus": "string",
    "input": {
        "occp_text": "string",
        "tasks_text": "string"
    },
    "result": [
        {
            "codeCategory": "string",
            "codeLabel": "string",
            "codeConfidence": number
        }
    ],
}
2. Coding a small batch of free text records
HTTP/1.1 200 OK 
Content-type: application/json 
[
    {
        "recordId": "string",
        "codeStatus": "string",
        "input": {
            "occp_text": "string",
            "tasks_text": "string"
        },
        "result": [
            {
                "codeCategory": "string",
                "codeLabel": "string", 
                "codeConfidence": number
            }
        ],
    }
]

Response elements

If the action is successful, the service sends back an HTTP 200 response. The API returns either a SynchronousCodeResponse object or an array of SynchronousCodeResponse objects corresponding to the input records.

Errors

For information about synchronous coding errors, see Errors and suggested actions. 

Examples

(Also see Integration script examples for example PowerShell single record and small batch coding scripts.)

 

 Successfully coded a single record using only one free text field:
Sample request
POST /v1/topics/osca/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorization: example token
{
    "record": {
        "occp_text": "Software developer. Writes code, tests"
    },
    "numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
{
    "codeStatus": "successful",
    "input": {
        "occp_text": "Software developer. Writes code, tests"
    },
    "result": [{
        "codeCategory": "261313",
        "codeLabel": "Software Engineer",
        "codeConfidence": 0.6093962788581848
    },{
        "codeCategory": "261312",
        "codeLabel": "Developer Programmer",
        "codeConfidence": 0.43940293565392494
    },{
        "codeCategory": "261399",
        "codeLabel": "Software and Applications Programmers nec",
        "codeConfidence": 0.43756575286388397
    }]
}

 

 Successfully coded a single record using all free text fields:
Sample request
POST /v1/topics/osca/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorization: example token
{
    "record": {
        "occp_text": "software developer",
        "tasks_text": "writing code and unit tests"
    },
    "numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
{
    "codeStatus": "successful",
    "input": {
        "occp_text": "software developer",
        "tasks_text": "writing code and unit tests"
    },
    "result": [{
        "codeCategory": "261313",
        "codeLabel": "Software Engineer",
        "codeConfidence": 0.6093962788581848
    },{
        "codeCategory": "261312",
        "codeLabel": "Developer Programmer",
        "codeConfidence": 0.43940293565392494
    },{
       "codeCategory": "261399",
       "codeLabel": "Software and Applications Programmers nec",
       "codeConfidence": 0.43756575286388397
    }]
}

 

 Unsuccessfully coded a single record using only one free text field:
Sample request
POST /v1/topics/osca/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorization: example token
{
    "record": {
        "occp_text": "Software developer. Writes code, tests"
    },
    "numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
{
    "codeStatus": "unsuccessful",
    "input": {
        "occp_text": "Software developer. Writes code, tests"
    },
    "result": [ ]
}

 

 Coding a small batch of records:
Sample request
POST /v1/topics/osca/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorization: example token
{
    "records": [
        {
            "occp_text": "software developer",
            "tasks_text": "writing code and unit tests"
        }, {
            "occp_text": "Paramedic, respond to emergencies"
        }, {
            "recordId": "1",
            "occp_text": "Sales assistant"
        }
    ],
    "numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
[
    {
        "codeStatus": "successful",
        "input": {
           "occp_text": "software developer",
            "tasks_text": "writing code and unit tests"
        },
        "result": [{
            "codeCategory": "261313",
            "codeLabel": "Software Engineer",
            "codeConfidence": 0.6093962788581848
        },{
            "codeCategory": "261312",
            "codeLabel": "Developer Programmer",
            "codeConfidence": 0.43940293565392494
        },{
            "codeCategory": "261399",
            "codeLabel": "Software and Applications Programmers",
            "codeConfidence": 0.43756575286388397
        }]
    }, {
        "codeStatus": "unsuccessful",
        "input": {
            "occp_text": "Paramedic, respond to emergencies"
        },
        "result": [ ]
    }, {
        "recordId": "1",
        "codeStatus": "unsuccessful",
        "input": {
            "occp_text": "Sales assistant"
        },
        "result": [ ]
    }
]

Coding against a specific model

This endpoint is used to code a single or small batch of free text records against the specified coding topic, using the specified model.

Request syntax

Depending on whether you are coding a single record or a small batch of records, your request will follow one of the following formats:

1. Coding a single free text record against a specific model
POST /v1/topics/{topic}/models/{model}/code HTTP/1.1
Host: string
Content-type: application/json
Authorization: string
{
    "record": {
        "occp_text": "string",
        "tasks_text": "string"
    }
    "numberOfSuggestions": number
}

2. Coding records against a specific model 
POST /v1/topics/{topic}/models/{model}/code HTTP/1.1 
Host: string
Content-type: application/json
Authorization: string
{
    "records": [
        {
            "recordId": "string",
            "occp_text": "string",
            "tasks_text": "string"
        }
    ],
    "numberOfSuggestions": number
}
URI request parameters
topicThe uriName of the topic against which the record is coded. This can be acquired by listing the available topics.
Required: Yes
modelThe model GUID for the model you would like to use to code records. This can be acquired by listing the available models for your topic.
Required: Yes
Request body
recordThe free text record to be coded.                                                                                                     
Type: Record object, following the input format specified by the model.
Required: No, but either record or records must be provided.
recordsThe free text records to be coded.
Type: Array of Record objects, following the input format specified by the model. Each item may optionally specify an additional string value recordId.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: No, but either record or records must be provided.
numberOfSuggestionsThe number of suggested codes to be provided if the record cannot be coded successfully. The maximum value of this field is 16.
Type: Number
Required: No

Response syntax

The response of this endpoint will depend on whether your input request contained a single record or a small batch of records.

1. Coding a single free text record
HTTP/1.1 200 OK
Content-type: application/json
{
    "codeStatus": "string",
    "input": {
        "occp_text": "string",
        "tasks_text": "string"
    },
       "result": [
        {
            "codeCategory": "string",
            "codeLabel": "string",
            "codeConfidence": number
        }
    ],
}
2. Coding a small batch of free text records
HTTP/1.1 200 OK 
Content-type: application/json 
[
    {
        "recordId": "string",
        "codeStatus": "string",
        "input": {
            "occp_text": "string",
            "tasks_text": "string"
        },
        "result": [
            {
                "codeCategory": "string",
                "codeLabel": "string",
                "codeConfidence": number
            }
        ],
    }
]

Response elements

If the action is successful, the service sends back an HTTP 200 response. The API returns either a SynchronousCodeResponse object or an array of SynchronousCodeResponse objects corresponding to the input records. 

Errors

For information about synchronous coding errors, see Errors and suggested actions. 

Examples

(Also see Integration script examples for example PowerShell single record and small batch coding scripts.)

 Successfully coded a single record against a specific model:
Sample request
POST /v1/topics/osca/models/GUID/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorization: example token
{
    "record": {
        "occp_text": "software developer",
        "tasks_text": "writing code and unit tests"
    },
    "numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
{
    "codeStatus": "successful",
    "input": {
        "occp_text": "software developer",
        "tasks_text": "writing code and unit tests"
    },
    "result": [{
        "codeCategory": "261313",
        "codeLabel": "Software Engineer",
        "codeConfidence": 0.6093962788581848
    },{
        "codeCategory": "261312",
        "codeLabel": "Developer Programmer",
        "codeConfidence": 0.43940293565392494
    },{
        "codeCategory": "261399",
        "codeLabel": "Software and Applications Programmers nec",
        "codeConfidence": 0.43756575286388397
    }]
}
 Coding a small batch of records against a specific model:
Sample request
POST /v1/topics/osca/models/GUID/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorization: example token
{
    "records": [
        {
            "occp_text": "software developer",
            "tasks_text": "writing code and unit tests"
        }, {
            "occp_text": "Paramedic, respond to emergencies"
        }, {
            "recordId": "1",
            "occp_text": "Sales assistant"
        }
    ],
    "numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
[
    {
        "codeStatus": "successful",
        "input": {
            "occp_text": "software developer",
            "tasks_text": "writing code and unit tests"
        },
        "result": [{
           "codeCategory": "261313",
            "codeLabel": "Software Engineer",
            "codeConfidence": 0.6093962788581848
        },{
            "codeCategory": "261312",
            "codeLabel": "Developer Programmer",
           "codeConfidence": 0.43940293565392494
        },{
            "codeCategory": "261399",
            "codeLabel": "Software and Applications Programmers",
            "codeConfidence": 0.43756575286388397
        }]
    }, {
        "codeStatus": "unsuccessful",
        "input": {
            "occp_text": "Paramedic, respond to emergencies"
        },
        "result": [ ]
    }, {
        "recordId": "1",
        "codeStatus": "unsuccessful",
        "input": {
            "occp_text": "Sales assistant"
        },
        "result": [ ]
    }
]