Data & API Standards

When integrating with our API, it is important to know the general standards across our endpoints as well as the expected formats for sending and receiving various data types.

Overview of API Standards

JSON Standard

All payloads needs to be correct JSON, and returned data or data from webhooks will always be returned in JSON.

---

Shared Headers

All payloads sent should contain the following headers:

Key	Value
Authorization	Bearer <YOUR API KEY>
Content-Type	application/json
Accept	application/json
user-agent	<YOUR USER AGENT>

Remember to replace <YOUR API KEY> for your unique API key (learn more) and <YOUR USER AGENT> with the tool you're using to send API calls (for many tools, this is often automatically included).

---

Data Type Standards

Numbers

• Format: Decimal numbers (e.g., 12345.67 or 1000000)

• Note: Avoid using commas or other delimiters. Use a period (.) for decimal points. Note that number parameters are generally sent without quotation marks in JSON, eg. {"number":19} and not {"number":"10"}.

---

Boolean

• Format: true or false

• Note: Note that boolean parameters are generally sent without quotation marks in JSON, eg. {"boolean_key":true} and not {"boolean_key":"true"}.

---

DateTime

• Format: ISO 8601(YYYY-MM-DDTHH:MM:SS.sssZ, e.g. 1980-10-10T04:00:00.000Z)

• Note: This format represents the ISO 8601 date-time format, which is a standard format used across web applications. The 'T' separates the date and time, and the 'Z' indicates that the time is in UTC.

---

Address

• Format: A full or partial address as recognized by Google Maps (e.g., "1600 Amphitheatre Parkway, Mountain View, CA").

• Note: If not all components of the address are provided, White Swan's systems will make a best guess on the missing details. It's recommended to provide as complete an address as possible for the most accurate results.

---

Text

• Format: Alphanumeric characters, symbols, and special characters.

• Note: This field is versatile and can accommodate a wide range of input. Ensure the content is relevant and contextually appropriate for the intended use.

---

Multiple-Choice Fields

• Format: Pre-defined options defined in documentation.

• Note: Ensure that data provided for these fields matches exactly one of the alternatives provided in the documentation. Using options outside of these predefined choices may result in errors or unexpected outcomes.

---

Lists

• Format: A JSON formatted list, eg.

["List item 1","List item 2"]

---

Object Lists

• Format: A JSON formatted object list, eg:

{
"object_list":[
{"string":"value","number":10},
{"string":"value2","number":20}
]
}

• Note: When object lists are shown in this documentation, the input for each item is shown below, starting each input with -.