Search code examples
apiarchitecturestandardsapi-designpayload

What is the best practice to design a phone number field for API payload?


Among the following two payload structures, what is the best practice and why? I have searched a few services that has phone number fields in their payload, but I got a fifty-fifty result. Some use the first type, and the rest the second.

Separate country code and number

“contact”: {
    “channel”: “phone”,
    “country_code”: “+44”,
    “number”: “2387648”
}

Country code and number together

“contact”: {
    “channel”: “phone”,
    “number”: “+442387648”
}

Solution

  • In my opinion, this only depends on the question if you ever need to handle the country code separately in your system - for example for displaying only actual number or for automatically identifying the country (e.g. using a mapping table).

    If this is not the case, I do not see a reason to transmit the phone number in two parts.