StreamlineAppearance
Search URA Tin Verification Requests
In case your system would like to search for the existing Tin Verification requests, you can use the following end point.
Endpoints
| Environment | URL |
|---|---|
| Sandbox | https://api-test.streamline.laboremus.ug/tinid-test/api/tins?v=2.0 |
| Production | https://api.streamline.laboremus.ug/tin/api/tins?v=2.0 |
Request
Request Type : GET
Authorization
There are two ways to be authorized when making this request.
js
const token = 'eyJhbGciOiJIUzI1NiIsInR5.eyJzd...ssw5c'
axios.get(API_ENDPOINT,
headers: {
Authorization: `Bearer ${token}`
}
)const token = 'eyJhbGciOiJIUzI1NiIsInR5.eyJzd...ssw5c'
axios.get(API_ENDPOINT,
headers: {
Authorization: `Bearer ${token}`
}
)js
import axios from 'axios'
import oauth from 'axios-oauth-client'
const getClientCredentials = oauth.clientCredentials(
axios.create(),
'https://oauth.com/2.0/token',
'CLIENT_ID',
'CLIENT_SECRET'
)
const auth = await getClientCredentials('OPTIONAL_SCOPES')
// => { "access_token": "...", "expires_in": 900, ... }
axios.get(API_ENDPOINT,
headers: {
Authorization: `Bearer ${auth.access_token}`
}
)import axios from 'axios'
import oauth from 'axios-oauth-client'
const getClientCredentials = oauth.clientCredentials(
axios.create(),
'https://oauth.com/2.0/token',
'CLIENT_ID',
'CLIENT_SECRET'
)
const auth = await getClientCredentials('OPTIONAL_SCOPES')
// => { "access_token": "...", "expires_in": 900, ... }
axios.get(API_ENDPOINT,
headers: {
Authorization: `Bearer ${auth.access_token}`
}
)INFO
Always add your Subscription key to the request.
js
axios.get(API_ENDPOINT,
headers: {
'Ocp-Apim-Subscription-Key': 'd484a1f0d34f43019'
}
)axios.get(API_ENDPOINT,
headers: {
'Ocp-Apim-Subscription-Key': 'd484a1f0d34f43019'
}
)js
const res = await axios.get(API_ENDPOINT, {
params: {
Ocp-Apim-Subscription-Key: 'd484a1f0d34f43019'
}
});const res = await axios.get(API_ENDPOINT, {
params: {
Ocp-Apim-Subscription-Key: 'd484a1f0d34f43019'
}
});Path Parameters Values
| Name | Type | Required | Description |
|---|---|---|---|
| id | string(uuid) | yes | The Unique ID of a Tin Verification request |
Query Parameters Values
| Name | Type | Required | Description |
|---|---|---|---|
| Id | string | no | Search for a request using their unique Id |
| Tin | string | no | Search for a request using the Tax Identification Number |
| Date.From | string | no | The start date of the date range |
| Date.To | string | no | The end date of the date range |
| Status | string | no | Search using the status of the request |
| Initiator | string | no | Search for a request using the user that initiated the request |
| Pagination.Page | string | no | Page number |
| Pagination.ItemsPerPage | string | no | Number of requests returned per page |
| Pagination.TotalItems | string | no | Total number of requests |
| v | string | yes | The version of the API |
Response
Content type
application/json
Response Values
| Name | Type | Description |
|---|---|---|
| requests | Array of objects | The requests matching the search criteria |
| pagination | object | The district where it is located |
requests
| Name | Type | Description |
|---|---|---|
| id | string (uuid) | The unique Id of the request. |
| tin | string or null | Tin Number sent in the request payload. |
| errorCode | string or null | The code of the error returned. |
| errorDescription | string or null | The description of the error returned. |
| initiator | string or null | Names of the request initiator. |
| county | string or null | Tin assignee's county. |
| district | string or null | Tin assignee's district. |
| isCustomsAgent | string or null | Tin assignee is a custom agent ("Y"/"N") |
| isLicenseValid | string or null | Customs agent license validity (Present if Tin assignee is a customs agent). |
| licenseNumber | string or null | Customs agent license number (Present if Tin assignee is a customs agent) |
| mobileNumber | string or null | Tin assignee's mobile number. |
| postalAddress | string or null | Tin assignee's postal address. |
| registrationStatus | string or null | Tin assignee's registration status. |
| subCounty | string or null | Tin assignee's sub-county. |
| taxPayerEmail | string or null | Tin assignee's taxpayer email. |
| taxPayerName | string or null | Tin assignee's taxpayer name. |
| telephoneNumber | string or null | Tin assignee's taxpayer phone number. |
| typeofUser | string or null | Tin assignee's user type. |
| village | string or null | Tin assignee's village. |
| nitaFaultCode | string or null | Nita response error code. |
| nitaFaultMessage | string or null | Nita response error message. |
| nitaFaultDescription | string or null | Nita response error description. |
| nitaFaultAms | string or null | Nita Ams error response. |
| nitaFaultText | string or null | Nita error text response. |
| status | string (Enum: Pending, Completed, Failed) | The status of the request sent |
| sentAt | string or null (date-time) | Date the request was sent. |
| processedAt | string or null (date-time) | Date at which the verification request was processed. |
| createdAt | string or null (date-time) | Date at which the verification request was created. |
| lastUpdated | string or null (date-time) | Date at which the verification request was last updated. |
| isError | boolean | A flag to show whether the request has errors |
| errors | array of errors | The errors that are returned. |
errors
| Name | Type | Description |
|---|---|---|
| suggestion | string[] | List of suggestions related to the error. |
| code | string | The error code. |
| message | string | The short message describing the error. |
| description | string | A detailed description of the error. |
| type | string | The type or category of the error. |
pagination
| Name | Type | Description |
|---|---|---|
| page | integer | Page number |
| itemsPerPage | object | Number of requests returned per page |
| totalItems | string or null | Total number of requests |
Example Response Body
json
{
"requests": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"tin": "string",
"errorCode": "string",
"errorDescription": "string",
"initiator": "string",
"contactNumber": "string",
"county": "string",
"district": "string",
"isCustomsAgent": "string",
"isLicenseValid": "string",
"licenseNumber": "string",
"mobileNumber": "string",
"postalAddress": "string",
"registrationStatus": "string",
"subCounty": "string",
"taxPayerEmail": "string",
"taxPayerName": "string",
"telephoneNumber": "string",
"typeofUser": "string",
"village": "string",
"nitaFaultCode": "string",
"nitaFaultMessage": "string",
"nitaFaultDescription": "string",
"nitaFaultAms": "string",
"nitaFaultText": "string",
"status": "Pending",
"sentAt": "2019-08-24T14:15:22Z",
"processedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"lastUpdated": "2019-08-24T14:15:22Z",
"isError": true,
"errors": [
{
"suggestion": [
"The Tax Identification Number (TIN) provided is invalid. Please check and try again"
],
"code": "S0002",
"message": "INVALID_TAX_IDENTIFICATION_NUMBER",
"description": "The Tax Identification Number provided is invalid.",
"type": "Data"
}
]
}
],
"pagination": {
"page": 0,
"itemsPerPage": 0,
"totalItems": 0
}
}{
"requests": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"tin": "string",
"errorCode": "string",
"errorDescription": "string",
"initiator": "string",
"contactNumber": "string",
"county": "string",
"district": "string",
"isCustomsAgent": "string",
"isLicenseValid": "string",
"licenseNumber": "string",
"mobileNumber": "string",
"postalAddress": "string",
"registrationStatus": "string",
"subCounty": "string",
"taxPayerEmail": "string",
"taxPayerName": "string",
"telephoneNumber": "string",
"typeofUser": "string",
"village": "string",
"nitaFaultCode": "string",
"nitaFaultMessage": "string",
"nitaFaultDescription": "string",
"nitaFaultAms": "string",
"nitaFaultText": "string",
"status": "Pending",
"sentAt": "2019-08-24T14:15:22Z",
"processedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"lastUpdated": "2019-08-24T14:15:22Z",
"isError": true,
"errors": [
{
"suggestion": [
"The Tax Identification Number (TIN) provided is invalid. Please check and try again"
],
"code": "S0002",
"message": "INVALID_TAX_IDENTIFICATION_NUMBER",
"description": "The Tax Identification Number provided is invalid.",
"type": "Data"
}
]
}
],
"pagination": {
"page": 0,
"itemsPerPage": 0,
"totalItems": 0
}
}Error Response
400 Bad Request
application/json
| Name | Type | Description |
|---|---|---|
| type | string or null | Type of error response |
| title | string or null | The title of the error response |
| status | integer(int32) | The status of the error response |
| traceId | string or null | The traceId of the error request producing the error |
| errors | object | Object defining the errors |
errors
| Name | Type | Description |
|---|---|---|
| property | Array of strings | The definition of the errors |
401 Unauthorized
application/json
| Name | Type | Description |
|---|---|---|
| error | object(Error) | Type of error response |
Error
| Name | Type | Description |
|---|---|---|
| code | string or null | The Error code |
| message | string or null | The Error message |
403 Forbidden
application/json
| Name | Type | Description |
|---|---|---|
| error | object(Error) | Type of error response |
Error
| Name | Type | Description |
|---|---|---|
| code | string or null | The Error code |
| message | string or null | The Error message |
404 Not Found
application/json
| Name | Type | Description |
|---|---|---|
| error | object(Error) | Type of error response |
Error
| Name | Type | Description |
|---|---|---|
| code | string or null | The Error code |
| message | string or null | The Error message |
500 Server Error
application/json
| Name | Type | Description |
|---|---|---|
| error | object(Error) | Type of error response |
Error
| Name | Type | Description |
|---|---|---|
| code | string or null | The Error code |
| message | string or null | The Error message |
Error Codes
When working with our TIN API, you'll encounter errors shown below. Each type of error comes with an appropriate code and suggestion to aid in troubleshooting.
All errors share the same basic response format.code indicating the error code,message providing an overview of the error, description to show more information about the error, suggestion to aid in troubleshooting and type describing the error type
| Code | Message | Description | Suggestion | Type |
|---|---|---|---|---|
| S0001 | FAILED_TO_VERIFY_TAX_IDENTIFICATION_NUMBER | Failed to verify Tax Identification Number | Something went wrong, Please contact support at email support@laboremus.ug | Fatal |
| S0002 | INVALID_TAX_IDENTIFICATION_NUMBER | The Tax Identification Number provided is invalid. | The Tax Identification Number (TIN) provided is invalid. Please check and try again | Data |
| S0003 | INVALID_CREDENTIALS | The connection credentials provided are invalid. | Please check whether the subscription key is correct or contact support at email support@laboremus.ug | Authentication |
| S0004 | UNKNOWN_ERROR | An unknown error has occurred, preventing the requested action from being completed. | Please try again later.If the issue persists, contact our support team at support@laboremus.ug with details about the action you were attempting to perform. | Fatal |