Many of the Deputy APIs rely on id numbers when referencing states and countries in the product. Due to this you will likely at some point need to retrieve these id numbers to use in other API requests. Follow the below guide on how to get this data.

📘

Storing the Country/State IDs

To save development effort you may decide to store the list of id numbers for the state and country records in Deputy within your own system. If you choose to do this, you should every so often run a refresh to ensure you have the most recent data.

The State and Country id numbers are found by using the Resource API. The resource API is a powerful part of the Deputy API platform that allows you to filter data via query searches and it is this tool that you use to retrieve the state and country id numbers.

Country ID numbers

Follow the below guide to retrieve country id numbers from the Deputy System

Base URL

curl --request POST 'https://{install}.{geo}.deputy.com/api/v1/resource/Country/QUERY'

Sample Payload

In the sample we are going to be searching for the country id number for the country Australia

{
    "search": {
        "s1": {
            "field": "Country",
            "type": "lk",
            "data":"Austr%"
        }
    }
}

The payload defines that this is a search payload and we are searching the Country field for names which has a name like Austr%. It is possible using the search API to include wildcard % at the start and end of a string. For example you could use %ustral% and get the same result of Australia.

You do not have to use the lk like operand. Instead you could search via the full country name using eq equal operand instead. It's up to you how best you think you can achieve your search.

🚧

More than one result

If you are using the like operand, it is possible for you to get more than one result in the array even when the specific country name is provided. Please keep this in mind when looking at responses from the API. If you use the equals operand, as this looks for a direct match this will not occur.

Response

[
    {
        "Id": 13,
        "Code": "AU",
        "CodeA3": "AUS",
        "Region": "AU",
        "Active": true,
        "SortOrder": 1,
        "Country": "Australia",
        "ZipValidatePreg": "/\\d{4}/",
        "PhoneDisplayPreg": null,
        "Creator": 1,
        "Created": "2009-03-03T13:43:39+11:00",
        "Modified": "2009-08-07T15:19:12+10:00",
        "_DPMetaData": {
            "System": "Country",
            "CreatorInfo": {
                "Id": 1,
                "DisplayName": "Simon Hutchinson",
                "EmployeeProfile": 1,
                "Employee": 1,
                "Photo": "https://photo2.deputy.com/deputec_b220523232117_1550/-135x135_f65257936760692b225cad7c3f689c80.jpg?Expires=1690942736&Signature=GAaqHCWSJaJc6NLBL3tdH1kiaWdNicEmszR7w5EAdxpqWsfBWIDt0z6j-gQp~ct5QR~1oQ1fyg7YSfH21n5pqkph6rpILdf~8o31p9Onuy3UYzCLZsTb5pzqkdW2QzV3G7T~kVJpZCiDpPWoGeNV64gTiHNsUPstMjSgStQ6khI_&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ",
                "Pronouns": 0,
                "CustomPronouns": ""
            }
        }
    }
  ]

You will get a number of pieces of information related to how that country fits into the Deputy platform in the response. However the key number you will be looking for to use in other API endpoints is the Id field. In this example the Id is 13, meaning that for example if you wanted to reference the country of Australia in a different endpoint that required the country id number, you would include 13.

State ID numbers

The process to get the state id numbers is very similar however geographical differences should be considered. For example US states have a length of two whilst Australian states have a length of three.

📘

Multi-region state responses

It is possible to get a response from the Deputy API that has states from many regions within it. You can tell which country the state is linked to via the Country id number in the response.

In the sample we are going to search for Id number for the the state of New York inside the Deputy system.

Base URL

curl --request POST 'https://{install}.{geo}.deputy.com/api/v1/resource/State/QUERY'

Sample Payload

{
    "search": {
        "s1": {
            "field": "State",
            "type": "lk",
            "data":"New Y%"
        }
    }
}

This payload defines that we are searching the State field for names that are like New Y% (again using a wildcard). Again you do not have to use the lk like operand and could use eq equals operand if you had the exact text you were looking for.

🚧

More than one result

If you are using the like operand, it is possible for you to get more than one result in the array even when the specific country name is provided. Please keep this in mind when looking at responses from the API. If you use the equals operand, as this looks for a direct match this will not occur.

Response

[
    {
        "Id": 44,
        "Country": 224,
        "Code": "NY",
        "Active": true,
        "SortOrder": 10,
        "State": "New York",
        "Creator": 1,
        "Created": "2009-03-03T14:31:40+11:00",
        "Modified": "2009-03-12T12:44:10+11:00",
        "_DPMetaData": {
            "System": "State",
            "CreatorInfo": {
                "Id": 1,
                "DisplayName": "Simon Hutchinson",
                "EmployeeProfile": 1,
                "Employee": 1,
                "Photo": "https://photo2.deputy.com/deputec_b220523232117_1550/-135x135_f65257936760692b225cad7c3f689c80.jpg?Expires=1690942736&Signature=GAaqHCWSJaJc6NLBL3tdH1kiaWdNicEmszR7w5EAdxpqWsfBWIDt0z6j-gQp~ct5QR~1oQ1fyg7YSfH21n5pqkph6rpILdf~8o31p9Onuy3UYzCLZsTb5pzqkdW2QzV3G7T~kVJpZCiDpPWoGeNV64gTiHNsUPstMjSgStQ6khI_&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ",
                "Pronouns": 0,
                "CustomPronouns": ""
            }
        }
    }
]

You will get a response that details a number of pieces of information about the State(s) record(s) in the Deputy platform. The key number you will likely be looking for will be the Id number in the record. It is this number which allows you to reference that specific state when working with the other Deputy API endpoints. In the example the Id is 44 meaning you would use the state Id of 44 when working with the other Deputy API endpoints to reference New York.