I am developing for the

market, looking for the

API Documentation.

Home

>

API Products

>

United Kingdom - Utilities API Documentation

Utilities

Summary

The Utilities APIs allow you to retrieve an array of valid values, field properties and validations applied for a specific market. This simplifies multimarket app development and helps to identify country-specific variations.

The Utilities API uses the client_credentials grant type, for authorization details CLICK HERE

Want to try this API out on our Playground?

Go play now
Endpoints on this page
get /v1/emea/utilities/employers Retrieve employers details
get /v1/ru/utilities/addresses KladrAddressSearch
get /v1/utilities/referenceData/{referenceCode} Retrieve valid values

Retrieve employers details

get /v1/emea/utilities/employers
Description

This API allows to search for employers details based on the employer search parameters

Header Parameters
client_id
string required
The client ID you received while Onboarding with Citi to use these API's. This will be generated and shared while registring in the developer portal.
Authorization
string required
The Authorization Token
countryCode
string Optional
Country code in 2 character ISO 3166 format.
businessCode
string Optional
The 3 character business code. Use GCB for consumer banking.
uuid
string required
128 bit UUID that you generate for every request
Accept
string required
Content-Types that are acceptable for the response. Currently we support application/json.
Accept-Language
string Optional
List of acceptable human languages for response
Content-Type
string required
The media type of the body of the request (used with POST and PUT requests). Currently we support application/json
clientDetails
string Optional
Device and browser information. Refer the developer portal for more information. Please ensure the header is base64 encoded
Query Parameters
employerName
string Optional
Employer name
employerRegistrationNumber
string Optional
Employer Registration number
employerTaxRegistrationNumber
string Optional
Employer tax registration number
  • cURL
  • Ruby
  • Python
  • PHP
  • Java
  • Node
  • Go
  • Swift

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Responses
200

Successful operation.
Definitions
  • employersDetails
      • employerName
        • Employer Name
        • type : string
      • employerRegistrationNumber
        • Employer Registration number
        • type : string
      • employerTaxRegistrationNumber
        • Employer tax registration number
        • type : string
      • employerAddressDetail
        • properties : Array
Example Response for get /v1/emea/utilities/employers
{
    "employersDetails": {
        "employerName": "CITI",
        "employerRegistrationNumber": "1027700035769",
        "employerTaxRegistrationNumber": "7708004767",
        "employerAddressDetail": {
            "addressLine1": "8-10 biuld. 1",
            "addressLine2": "Gasheka Street",
            "addressLine3": "Gasheka Street",
            "addressLine4": "Gasheka Street",
            "cityName": "Moscow",
            "districtName": "Giaginsky District",
            "state": "Russia",
            "provinceCode": "Moscow",
            "postalCode": "125047"
        }
    }
}
400

TypeCodeDetails
invalidinvalidRequestMissing or invalid Parameters
Definitions
  • errors
Response Schema for get /v1/emea/utilities/employers
{
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of one or more errors",
            "items": {
                "properties": {
                    "type": {
                        "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
                        "enum": [
                            "error",
                            "warn",
                            "invalid",
                            "fatal"
                        ],
                        "type": "string"
                    },
                    "code": {
                        "description": "Error code which qualifies the error",
                        "type": "string"
                    },
                    "details": {
                        "description": "Human readable explanation specific to the occurrence of the problem",
                        "type": "string"
                    },
                    "location": {
                        "description": "The name of the field that resulted in the error",
                        "type": "string"
                    },
                    "moreInfo": {
                        "description": "URI to human readable documentation of the error",
                        "type": "object"
                    }
                },
                "required": [
                    "type",
                    "code"
                ]
            }
        }
    }
}
401

TypeCodeDetails
errorunAuthorizedAuthorization credentials are missing or invalid
Definitions
  • errors
Response Schema for get /v1/emea/utilities/employers
{
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of one or more errors",
            "items": {
                "properties": {
                    "type": {
                        "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
                        "enum": [
                            "error",
                            "warn",
                            "invalid",
                            "fatal"
                        ],
                        "type": "string"
                    },
                    "code": {
                        "description": "Error code which qualifies the error",
                        "type": "string"
                    },
                    "details": {
                        "description": "Human readable explanation specific to the occurrence of the problem",
                        "type": "string"
                    },
                    "location": {
                        "description": "The name of the field that resulted in the error",
                        "type": "string"
                    },
                    "moreInfo": {
                        "description": "URI to human readable documentation of the error",
                        "type": "object"
                    }
                },
                "required": [
                    "type",
                    "code"
                ]
            }
        }
    }
}
500

TypeCodeDetails
fatalserverUnavailableThe request failed due to an internal error
Definitions
  • errors
Response Schema for get /v1/emea/utilities/employers
{
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of one or more errors",
            "items": {
                "properties": {
                    "type": {
                        "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
                        "enum": [
                            "error",
                            "warn",
                            "invalid",
                            "fatal"
                        ],
                        "type": "string"
                    },
                    "code": {
                        "description": "Error code which qualifies the error",
                        "type": "string"
                    },
                    "details": {
                        "description": "Human readable explanation specific to the occurrence of the problem",
                        "type": "string"
                    },
                    "location": {
                        "description": "The name of the field that resulted in the error",
                        "type": "string"
                    },
                    "moreInfo": {
                        "description": "URI to human readable documentation of the error",
                        "type": "object"
                    }
                },
                "required": [
                    "type",
                    "code"
                ]
            }
        }
    }
}

KladrAddressSearch

get /v1/ru/utilities/addresses
Description

This API is used to retrieve address from KLADR System based on search parameters.

Header Parameters
client_id
string required
The client ID you received while Onboarding with Citi to use these API's. This will be generated and shared while registring in the developer portal.
Authorization
string required
The Authorization Token
countryCode
string Optional
Country code in 2 character ISO 3166 format.
businessCode
string Optional
The 3 character business code. Use GCB for consumer banking.
uuid
string required
128 bit UUID that you generate for every request
Accept
string required
Content-Types that are acceptable for the response. Currently we support application/json.
Accept-Language
string Optional
List of acceptable human languages for response
Content-Type
string required
The media type of the body of the request (used with POST and PUT requests). Currently we support application/json
clientDetails
string Optional
Device and browser information. Refer the developer portal for more information. Please ensure the header is base64 encoded
Query Parameters
searchName
string required
search name for the kladr address , support below search name: "City","Street","Doma"
searchValue
string Optional
User input value kladr code address search , this can be full name or practical name of the city/street/doma, but atleast two characters are required.
kladrCode
string required
High level kladr code. KLADR refers to Russian postal address database.
  • cURL
  • Ruby
  • Python
  • PHP
  • Java
  • Node
  • Go
  • Swift

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Responses
200

Successful operation.
Definitions
  • kladrAddress
Example Response for get /v1/ru/utilities/addresses
{
    "kladrAddress": []
}
400

invalidinvalidRequestMissing or invalid Parameters
invalidinvalidControlFlowIdControl flow ID is invalid
Definitions
  • errors
Response Schema for get /v1/ru/utilities/addresses
{
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of one or more errors",
            "items": {
                "properties": {
                    "type": {
                        "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
                        "enum": [
                            "error",
                            "warn",
                            "invalid",
                            "fatal"
                        ],
                        "type": "string"
                    },
                    "code": {
                        "description": "Error code which qualifies the error",
                        "type": "string"
                    },
                    "details": {
                        "description": "Human readable explanation specific to the occurrence of the problem",
                        "type": "string"
                    },
                    "location": {
                        "description": "The name of the field that resulted in the error",
                        "type": "string"
                    },
                    "moreInfo": {
                        "description": "URI to human readable documentation of the error",
                        "type": "object"
                    }
                },
                "required": [
                    "type",
                    "code"
                ]
            }
        }
    }
}
401

TypeCodeDetails
errorunAuthorizedAuthorization credentials are missing or invalid
Definitions
  • errors
Response Schema for get /v1/ru/utilities/addresses
{
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of one or more errors",
            "items": {
                "properties": {
                    "type": {
                        "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
                        "enum": [
                            "error",
                            "warn",
                            "invalid",
                            "fatal"
                        ],
                        "type": "string"
                    },
                    "code": {
                        "description": "Error code which qualifies the error",
                        "type": "string"
                    },
                    "details": {
                        "description": "Human readable explanation specific to the occurrence of the problem",
                        "type": "string"
                    },
                    "location": {
                        "description": "The name of the field that resulted in the error",
                        "type": "string"
                    },
                    "moreInfo": {
                        "description": "URI to human readable documentation of the error",
                        "type": "object"
                    }
                },
                "required": [
                    "type",
                    "code"
                ]
            }
        }
    }
}
404

TypeCodeDetails
errorinvalidApplicationApplication not found or invalid
Definitions
  • errors
Response Schema for get /v1/ru/utilities/addresses
{
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of one or more errors",
            "items": {
                "properties": {
                    "type": {
                        "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
                        "enum": [
                            "error",
                            "warn",
                            "invalid",
                            "fatal"
                        ],
                        "type": "string"
                    },
                    "code": {
                        "description": "Error code which qualifies the error",
                        "type": "string"
                    },
                    "details": {
                        "description": "Human readable explanation specific to the occurrence of the problem",
                        "type": "string"
                    },
                    "location": {
                        "description": "The name of the field that resulted in the error",
                        "type": "string"
                    },
                    "moreInfo": {
                        "description": "URI to human readable documentation of the error",
                        "type": "object"
                    }
                },
                "required": [
                    "type",
                    "code"
                ]
            }
        }
    }
}
500

TypeCodeDetails
fatalserverUnavailableThe request failed due to an internal error
Definitions
  • errors
Response Schema for get /v1/ru/utilities/addresses
{
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of one or more errors",
            "items": {
                "properties": {
                    "type": {
                        "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
                        "enum": [
                            "error",
                            "warn",
                            "invalid",
                            "fatal"
                        ],
                        "type": "string"
                    },
                    "code": {
                        "description": "Error code which qualifies the error",
                        "type": "string"
                    },
                    "details": {
                        "description": "Human readable explanation specific to the occurrence of the problem",
                        "type": "string"
                    },
                    "location": {
                        "description": "The name of the field that resulted in the error",
                        "type": "string"
                    },
                    "moreInfo": {
                        "description": "URI to human readable documentation of the error",
                        "type": "object"
                    }
                },
                "required": [
                    "type",
                    "code"
                ]
            }
        }
    }
}

Retrieve valid values

get /v1/utilities/referenceData/{referenceCode}
Description

Returns an array of valid values and descriptions for the specified field

Path Parameters
referenceCode
string required
Reference Code
Header Parameters
Authorization
string required
The most recent Authorization token. This will have the format Bearer + {space} + {accessToken}. Example: Bearer KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==.
uuid
string required
128 bit random UUID generated uniquely for every request.
Accept
string required
Content-Type that are acceptable for the response.
client_id
string required
Client ID generated during application registration.
  • cURL
  • Ruby
  • Python
  • PHP
  • Java
  • Node
  • Go
  • Swift

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Responses
200

Successful operation.
Definitions
  • referenceDataDetails
Example Response for get /v1/utilities/referenceData/{referenceCode}
{
    "referenceDataDetails": []
}
400

TypeCodeDetails
invalidinvalidRequestMissing or invalid parameters
Definitions
  • type
    • Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again
    • enum : Array
    • type : string
  • code
    • Error code which qualifies the error
    • type : string
  • details
    • Human readable explanation specific to the occurrence of the problem
    • type : string
  • location
    • The name of the field that resulted in the error
    • type : string
  • moreInfo
    • URI to human readable documentation of the error
    • type : object
  • required
    • type
    • code
Response Schema for get /v1/utilities/referenceData/{referenceCode}
{
    "properties": {
        "type": {
            "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
            "enum": [
                "error",
                "warn",
                "invalid",
                "fatal"
            ],
            "type": "string"
        },
        "code": {
            "description": "Error code which qualifies the error",
            "type": "string"
        },
        "details": {
            "description": "Human readable explanation specific to the occurrence of the problem",
            "type": "string"
        },
        "location": {
            "description": "The name of the field that resulted in the error",
            "type": "string"
        },
        "moreInfo": {
            "description": "URI to human readable documentation of the error",
            "type": "object"
        }
    },
    "required": [
        "type",
        "code"
    ]
}
401

errorunAuthorizedAuthorization credentials are missing or invalid
Definitions
  • type
    • Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again
    • enum : Array
    • type : string
  • code
    • Error code which qualifies the error
    • type : string
  • details
    • Human readable explanation specific to the occurrence of the problem
    • type : string
  • location
    • The name of the field that resulted in the error
    • type : string
  • moreInfo
    • URI to human readable documentation of the error
    • type : object
  • required
    • type
    • code
Response Schema for get /v1/utilities/referenceData/{referenceCode}
{
    "properties": {
        "type": {
            "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
            "enum": [
                "error",
                "warn",
                "invalid",
                "fatal"
            ],
            "type": "string"
        },
        "code": {
            "description": "Error code which qualifies the error",
            "type": "string"
        },
        "details": {
            "description": "Human readable explanation specific to the occurrence of the problem",
            "type": "string"
        },
        "location": {
            "description": "The name of the field that resulted in the error",
            "type": "string"
        },
        "moreInfo": {
            "description": "URI to human readable documentation of the error",
            "type": "object"
        }
    },
    "required": [
        "type",
        "code"
    ]
}
403

erroraccessNotConfiguredThe requested operation is not configured to access this resource.
Definitions
  • type
    • Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again
    • enum : Array
    • type : string
  • code
    • Error code which qualifies the error
    • type : string
  • details
    • Human readable explanation specific to the occurrence of the problem
    • type : string
  • location
    • The name of the field that resulted in the error
    • type : string
  • moreInfo
    • URI to human readable documentation of the error
    • type : object
  • required
    • type
    • code
Response Schema for get /v1/utilities/referenceData/{referenceCode}
{
    "properties": {
        "type": {
            "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
            "enum": [
                "error",
                "warn",
                "invalid",
                "fatal"
            ],
            "type": "string"
        },
        "code": {
            "description": "Error code which qualifies the error",
            "type": "string"
        },
        "details": {
            "description": "Human readable explanation specific to the occurrence of the problem",
            "type": "string"
        },
        "location": {
            "description": "The name of the field that resulted in the error",
            "type": "string"
        },
        "moreInfo": {
            "description": "URI to human readable documentation of the error",
            "type": "object"
        }
    },
    "required": [
        "type",
        "code"
    ]
}
404

errorresourceNotFoundEmpty resource/resource not found
Definitions
  • type
    • Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again
    • enum : Array
    • type : string
  • code
    • Error code which qualifies the error
    • type : string
  • details
    • Human readable explanation specific to the occurrence of the problem
    • type : string
  • location
    • The name of the field that resulted in the error
    • type : string
  • moreInfo
    • URI to human readable documentation of the error
    • type : object
  • required
    • type
    • code
Response Schema for get /v1/utilities/referenceData/{referenceCode}
{
    "properties": {
        "type": {
            "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
            "enum": [
                "error",
                "warn",
                "invalid",
                "fatal"
            ],
            "type": "string"
        },
        "code": {
            "description": "Error code which qualifies the error",
            "type": "string"
        },
        "details": {
            "description": "Human readable explanation specific to the occurrence of the problem",
            "type": "string"
        },
        "location": {
            "description": "The name of the field that resulted in the error",
            "type": "string"
        },
        "moreInfo": {
            "description": "URI to human readable documentation of the error",
            "type": "object"
        }
    },
    "required": [
        "type",
        "code"
    ]
}
500

fatalserverUnavailableThe request failed due to an internal error
Definitions
  • type
    • Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again
    • enum : Array
    • type : string
  • code
    • Error code which qualifies the error
    • type : string
  • details
    • Human readable explanation specific to the occurrence of the problem
    • type : string
  • location
    • The name of the field that resulted in the error
    • type : string
  • moreInfo
    • URI to human readable documentation of the error
    • type : object
  • required
    • type
    • code
Response Schema for get /v1/utilities/referenceData/{referenceCode}
{
    "properties": {
        "type": {
            "description": "Invalid - Request did not confirm to the specification and was unprocessed and rejected. Please fix the value and try again",
            "enum": [
                "error",
                "warn",
                "invalid",
                "fatal"
            ],
            "type": "string"
        },
        "code": {
            "description": "Error code which qualifies the error",
            "type": "string"
        },
        "details": {
            "description": "Human readable explanation specific to the occurrence of the problem",
            "type": "string"
        },
        "location": {
            "description": "The name of the field that resulted in the error",
            "type": "string"
        },
        "moreInfo": {
            "description": "URI to human readable documentation of the error",
            "type": "object"
        }
    },
    "required": [
        "type",
        "code"
    ]
}