API Standards

The SalesKick API adheres to widely adopted RFCs and ISO standards for data formats. This page documents each standard, explains how it applies to the API, and provides examples of valid and invalid values.

Phone numbers (E.164)

All phone number fields follow the ITU-T E.164 international telephone numbering format.

Phone numbers must start with a + followed by the country code and subscriber number, with no spaces, hyphens, or parentheses. The maximum length is 15 digits (including the country code).

Value	Valid	Reason
+14155552671	Yes	US number with country code 1
+442071838750	Yes	UK number with country code 44
+5511998765432	Yes	Brazil number with country code 55
(415) 555-2671	No	Contains parentheses, spaces, and hyphens
415-555-2671	No	Missing + prefix and country code
+0123456789	No	Country code cannot start with 0
14155552671	No	Missing + prefix

JSON

1{
2  "phone_number": "+14155552671"
3}

Country codes (ISO 3166-1)

Country fields use ISO 3166-1 alpha-2 two-letter country codes.

Value	Valid	Reason
US	Yes	United States
CA	Yes	Canada
DE	Yes	Germany
USA	No	Alpha-3 code; the API requires alpha-2
us	No	Must be uppercase
United States	No	Full name not accepted

JSON

1{
2  "country": "US"
3}

State and province codes (ISO 3166-2)

State and province fields use ISO 3166-2 subdivision codes in the format {country}-{subdivision}.

Value	Valid	Reason
US-CA	Yes	California, United States
US-DC	Yes	District of Columbia
CA-ON	Yes	Ontario, Canada
CA	No	Missing subdivision code
California	No	Full name not accepted
us-ca	No	Country prefix must be uppercase

JSON

1{
2  "country": "US",
3  "state": "US-NY"
4}

Timestamps (ISO 8601 / RFC 3339)

All timestamp fields use ISO 8601 format as profiled by RFC 3339. Timestamps are always in UTC, indicated by the Z suffix.

Value	Valid	Reason
2024-02-17T10:45:23Z	Yes	Standard UTC timestamp
2024-02-17T10:45:23.123Z	Yes	With millisecond precision
2024-02-17T10:45:23.123456Z	Yes	With microsecond precision
2024-02-17T10:45:23+00:00	Yes	Explicit UTC offset
2024-02-17	No	Missing time component
2024-02-17 10:45:23	No	Space instead of T separator
02/17/2024	No	Not ISO 8601 format
1708166723	No	Unix timestamp not accepted

JSON

1{
2  "created_at": "2024-02-17T10:45:23Z",
3  "updated_at": "2024-02-17T14:30:00.000Z"
4}

Language tags (BCP 47)

Language and locale fields use BCP 47 language tags as defined in RFC 5646. Tags consist of a lowercase ISO 639-1 language code followed by an uppercase ISO 3166-1 region code, separated by a hyphen.

Value	Valid	Reason
en-US	Yes	English (United States)
es-US	Yes	Spanish (United States)
es-MX	Yes	Spanish (Mexico)
fr-CA	Yes	French (Canada)
pt-BR	Yes	Portuguese (Brazil)
en_US	No	Underscore instead of hyphen
EN-us	No	Language must be lowercase, region uppercase
english	No	Full language name not accepted

JSON

1{
2  "preferred_language": "en-US"
3}

Postal codes (USPS)

For US addresses, postal code fields accept standard USPS 5-digit ZIP codes or 9-digit ZIP+4 codes with a hyphen separator.

Value	Valid	Reason
94102	Yes	Standard 5-digit ZIP
94102-1234	Yes	ZIP+4 format
9410	No	Fewer than 5 digits
941021234	No	ZIP+4 missing hyphen
94102-123	No	ZIP+4 extension must be 4 digits
ABCDE	No	Must be numeric

JSON

1{
2  "postal_code": "94102-1234"
3}

Identifiers (UUID)

All resource identifiers use RFC 9562 Universally Unique Identifiers (UUIDs) in their canonical lowercase string representation.

Value	Valid	Reason
550e8400-e29b-41d4-a716-446655440000	Yes	Standard UUID format
550e8400e29b41d4a716446655440000	No	Missing hyphens
550e8400-e29b-41d4-a716	No	Incomplete UUID
not-a-uuid	No	Invalid format

JSON

1{
2  "id": "550e8400-e29b-41d4-a716-446655440000",
3  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
4  "payment_id": "789e0123-e89b-12d3-a456-426614174000"
5}

Currency codes (ISO 4217)

All monetary amounts include a currency field using ISO 4217 three-letter currency codes.

Value	Valid	Reason
USD	Yes	United States Dollar
CAD	Yes	Canadian Dollar
MXN	Yes	Mexican Peso
usd	No	Must be uppercase
US	No	Must be a 3-letter code
$	No	Currency symbols are not accepted

JSON

1{
2  "fee": {
3    "amount": 50,
4    "currency": "USD"
5  }
6}

Recurrence rules (RFC 5545)

Subscription schedules use recurrence rules as defined in RFC 5545 (iCalendar), expressed as an RRULE: string. This format describes how events repeat over time.

Format

A recurrence rule begins with the RRULE: prefix followed by one or more semicolon-separated properties:

RRULE:FREQ=<frequency>[;PROPERTY=VALUE...]

Key properties

Property	Description	Example values
FREQ	Required. Recurrence frequency.	DAILY, WEEKLY, MONTHLY, YEARLY
INTERVAL	How often the rule repeats (default: 1).	2 (every 2 weeks)
COUNT	Total number of occurrences before the schedule ends.	12
UNTIL	UTC datetime after which no more occurrences are generated.	20261231T000000Z
BYDAY	Days of the week. Use two-letter codes: MO, TU, WE, TH, FR, SA, SU.	MO,WE,FR
BYMONTHDAY	Day(s) of the month.	1, 15
BYMONTH	Month(s) of the year (1–12).	3, 6, 9, 12

Validity table

Value	Valid	Reason
RRULE:FREQ=MONTHLY;COUNT=12	Yes	Monthly, 12 occurrences
RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR	Yes	Every Monday, Wednesday, Friday
RRULE:FREQ=YEARLY;UNTIL=20261231T000000Z	Yes	Yearly until end of 2026
RRULE:FREQ=MONTHLY;INTERVAL=3	Yes	Every 3 months (quarterly)
RRULE:FREQ=DAILY;COUNT=30	Yes	Daily for 30 days
monthly	No	Missing RRULE: prefix and FREQ property
RRULE:INTERVAL=2	No	FREQ is required
P1M	No	ISO 8601 duration — not an RRULE string

Ending a subscription

To end a subscription, update the schedule field and add an UNTIL date. Do not delete the subscription.

JSON

1{
2  "schedule": "RRULE:FREQ=MONTHLY;UNTIL=20261231T000000Z"
3}

Examples

JSON

1{
2  "name": "Monthly Software License",
3  "schedule": "RRULE:FREQ=MONTHLY;COUNT=12"
4}

JSON

1{
2  "name": "Weekly Service",
3  "schedule": "RRULE:FREQ=WEEKLY;BYDAY=MO"
4}

JSON

1{
2  "name": "Annual Subscription",
3  "schedule": "RRULE:FREQ=YEARLY"
4}

Error responses (RFC 9457)

All error responses follow RFC 9457 Problem Details for HTTP APIs. For the full error response format, status codes, and validation error structure, see the Errors page.

Standards reference

Standard	Specification	Fields
ITU-T E.164	ITU-T E.164	phone_number
ISO 3166-1 alpha-2	ISO 3166	country
ISO 3166-2	ISO 3166	state
ISO 4217	ISO 4217	currency
ISO 8601 / RFC 3339	ISO 8601 / RFC 3339	created_at, updated_at, expires_at
BCP 47 / RFC 5646	BCP 47 / RFC 5646	preferred_language
USPS ZIP Code	USPS	postal_code
RFC 9562	RFC 9562	id, organization_id, payment_id
RFC 5545	RFC 5545	schedule
RFC 9457	RFC 9457	Error responses