API Standard Constants and Codes
- Bettina Lippisch
- Robin Heneghan
Postal Address Data
The following guidelines apply to handling data from our web service APIs that contain postal address information.
Country Codes
We use the ISO 3166-1 alpha-3 set of country codes in our addresses
State/Region Codes
For US states and Canadian Provinces, we expect data in the form of the two-character state abbreviation.
Postal Code
When providing ZIP code information for US addresses, try to provide a full 10-digit zip code (5 digit, dash, 4 digit) format. Some examples of US ZIP codes:
60062-1234
60601-1000
54445
Address Contact Types
Value | Description |
|---|---|
100 | Business Address |
110 | Home Address |
Phone Data
The following guidelines describe conventions for handling phone number contact data. Generally, we do not validate phone information for number of digits, however if alphabetic and certain punctuation characters are present in a phone number the data may be rejected.
Some examples of clean phone data
123 555 1212
123-555-1212
1235551212
1123-555-1212
0252929392001
Some examples of bad phone data:
123.555.1212
1235551212 m
123-555-1212 mobile
800-call-joe
Phone Contact Types
Value | Description |
|---|---|
200 | Business Phone |
210 | Home Phone |
230 | Mobile Phone |
240 | Fax |
250 | Foreign Phone |
260 | Foreign Fax |
270 | Pager |
Email Data
The following guidelines describe conventions for handling phone number contact data. We employ fairly strict validation on email address data. If the form of an email address is not valid (wrong number of characters, contains illegal characters), the data will be marked as invalid, which could result in the service returning an error, or at least marking the email data as invalid. There are a lot of publicly available email address validation routines, including regular expressions that can be used to implement basic email form validation.
Samples of bad email data:
Email Contact Types
Value | Description |
|---|---|
300 | Primary (Business) Email Address |
310 | Secondary (Home) Email Address |
Product Data
Use the below table to decode the “ProductType” element that is returned from the Brand Comprehensive Lookup Service.
Product Types
Value | Description |
|---|---|
1 | Magazine |
2 | Newsletter |
3 | Event |
4 | Catalog |
5 | Email Deployment |
6 | Association Membership |
7 | Website |
8 | Newsstand |
9 | Accounting |
10 | Sales |
Paid Subscription Data
Payment Status Codes
Use the below table to decode the “PaymentStatus” element that is returned from the Customer Subscriptions Lookup By Customer Id.
value | description | what it means |
|---|---|---|
1 | Paid on invoice. | Customer paid after being invoiced. |
2 | Paid with order. | Customer paid at the time of his order. |
3 | Credit. | Customer owes an outstanding balance on the subscription. |
5 | Grace. | Customer subscription is in grace. |
6 | Free. | Customer is being granted a free subscription, but isn’t necessarily qualified by the publisher. |
7 | Controlled. | Customer was selected by publisher to receive subscription for free. |
8 | Free Term. | Customer was granted a paid subscription at no cost. (free with expire date, formerly known as comp) |
Subscription Class Codes
Use the below table to decode the “SubscriptionClass” element that is returned from the Customer Subscription Lookup By Customer Id.
value | Description | Considered Active? | applies to |
|---|---|---|---|
1 | Active. For controlled magazine products, 1 denotes Active Controlled. | yes | All product types. |
2 | Active Non-Qualified | yes | Only products with paid circulation. |
3 | Qualified Reserve | no | Only products with controlled circulation. |
8 | Soft controlled kills | no | Only products with controlled circulation. |
9 | Controlled kills | no | Only products with controlled circulation. |
10 | ACS kills (Address Correction Service) | no | Only products having subscription address delivery. |
20 | Expire suspends | no | Subscription based products having an expiration date. |
21 | Future starts | no | Subscription based products having an expiration date. |
22 | Postal suspends | no | Only products having subscription address delivery. |
23 | Credit Suspends | no | Subscription based paid products. |
24 | Requested Suspends | no | Any product type. |
25 | Kill/Refunds | no | Subscription based paid products. |
50 | Passalong | no | Any product type. |
Credit Card Type Codes
Use the below table to provide the “CreditCardType” element to Save Customer and Order Paid API.
value | Description |
|---|---|
1 | Visa |
2 | Mastercard |
3 | American Express |
4 | Discover |
5 | Diners Club |
104 | Euro Card |
Table of Contents