Resources

Table of Contents

• Resource ID
  • id
  • bookmark
  • name
  • file
  • default
• Resource Types
  • Address Table Catalog
  • Address Table
  • Records
  • Record
  • Indexes
  • Index
  • Layouts
  • Layout
  • Selectivities
  • Selectivity
  • Company Catalog
  • Company
  • Permit Catalog
  • Permit
  • Publication Catalog
  • Publication

A resource is a persistent object that can be uniquely identified and represented as JSON. Users can create, read, update and delete resources using Resource Calls.

Resource ID

A resource ID uniquely identifies a resource. It is an array of string values identifying the resource. It is hierarchical. That is, each value identifies a resource relative to the resource identified by previous values.

The syntax of the resource ID depends on the type of resource, but these are some general rules.

• The first value always identifies a resource at the top level of the resource hierarchy,
  e.g. [ "addressTables" ].
• Some types of resource have children, in which case the resource ID of a child is obtained by appending a value to the resource ID of the parent,
  e.g. [ "addressTables", "1234567890" ] has a child, [ "addressTables", "1234567890", "indexes" ].
• Some types of resource have children that are alike. This is referred to as a collection.
  e.g. [ "addressTables", "1234567890", "selectivities" ] has children that are all selectivities.

id

Some types of resource have an auto-generated id property. The resource ID is obtained by appending the value of the id property to the resource ID of the parent,
e.g. the resource ID [ "addressTables", "1234567890" ] identifies the address table with the id "1234567890".

bookmark

Some types of resource have an auto-generated bookmark. The resource ID is obtained by appending the bookmark to the resource ID of the parent,
e.g. the resource ID [ "addressTables", "1234567890", "records", "AQAAAA==" ] identifies a record with the bookmark "AQAAAA==" in the address table with the id "1234567890".

name

Some types of resource have a name property that can be used to identify the resource by name using the name$ prefix with the value of the name property. A resource ID can be obtained by appending this value to the resource ID of the parent,
e.g. the resource ID [ "addressTables", "name$Conner" ] identifies the address table named Conner.

file

Some types of resource can be persisted to file using the file$ prefix with a file identifier consisting entirely of lower case letters. A resource ID can be obtained by appending this value to the resource ID of the parent,
e.g. the resource ID [ "companies", "file$listprocessor" ] identifies a company stored in the file named companies/catalog/listprocessor.json.

Note

The Data Marketing Services and Reporting modules do not support the file$ prefix.

default

Some types of resource support a default item in a collection. A resource ID for the default item can be obtained by appending default$ to the resource ID for the parent. This can only be used with the resourceGet() function,
e.g. the resource ID [ "addressTables", "1234567890", "layouts", "default$" ] identifies the default layout for the address table with the id "1234567890".

Resource Types

Supported resource types are shown in the table below. The table shows, for each resource type, whether or not it is a collection and what the Resource ID format is.

Resource Type	Collection	Resource ID
Essentials
└ Address table catalog	✓	[ "addressTables" ]
└ Address table		[ "addressTables", < id / name / file > ]
└ Records	✓	[ "addressTables", < id / name / file >, "records" ]
Record		[ "addressTables", < id / name / file >, "records", < bookmark > ]
└ Indexes	✓	[ "addressTables", < id / name / file >, "indexes" ]
Index		[ "addressTables", < id / name / file >, "indexes", < id / name / default > ]
└ Layouts	✓	[ "addressTables", < id / name / file >, "layouts" ]
Layout		[ "addressTables", < id / name / file >, "layouts", < id / name / default > ]
└ Selectivities	✓	[ "addressTables", < id / name / file >, "selectivities" ]
Selectivity		[ "addressTables", < id / name / file >, "selectivities", < id / name / default > ]
└ Company catalog	✓	[ "companies" ]
Company		[ "companies", < id / name / file > ]
└ Permit catalog	✓	[ "permits" ]
Permit		[ "permits", < id / name / file > ]
└ Publication catalog	✓	[ "publications" ]
Publication		[ "publications", < id / name / file > ]

Address Table Catalog

The address table catalog is a collection of address tables.

Address Table

An address table has an underlying database table, defined using the classId and connection properties, records, indexes, layouts, and selectivities.

The following services create an address table and add it to the catalog.

• addressTableCreateFromDatabase
• addressTableCreateFromPackage
• addressTableCreateFromTemplate

The following services require an address table.

• addressTableCreatePackage
• addressTableDelete
• addressTableExport
• addressTableImport
• addressTableModify
• containerTags
• dmsJob
• encodeTable
• eSubmission
• mailDat
• manifestReport
• modifyPresorted
• presort
• getPresorts
• postageStatement
• qualificationReport

An address table has the following properties:

The id, name, classId and connection properties are required. The id property is auto-generated and read only.

Name	Type	Description
id	string	Unique identifier
name	string	Name
classId	string	Class of the database (must be dbf)
connection	string	File name of the database (must be an xBase table)
LAYOUT_ID	string	id of the default layout
SEL_ID	string	id of the default selectivity
INDEXNAME	string	id of the default index
PASSWORD	string	internal use, do not modify
MAILER_ID	string	internal use, do not modify
OWNER_ID	string	internal use, do not modify
PROCESS_ID	string	internal use, do not modify
PREPFOR_ID	string	internal use, do not modify
HOLDER_ID	string	internal use, do not modify
SHOWDELETE	boolean	internal use, do not modify
NCOA_DATE	date	internal use, do not modify
DSF_DATE	date	internal use, do not modify
NCOADSFJOB	integer	internal use, do not modify
LABEL_REF	string	internal use, do not modify
REPORT_REF	string	internal use, do not modify
UDREP_REF	string	internal use, do not modify
COMPRCNT	integer	internal use, do not modify
DSTREP_REF	string	internal use, do not modify
FFRECEIVED	date	internal use, do not modify
PENCRYPTED	boolean	internal use, do not modify
ORDER	integer	internal use, do not modify
EXPORT_REF	string	internal use, do not modify
MODIFY_REF	string	internal use, do not modify
GROUP	string	internal use, do not modify
NOTES	string	internal use, do not modify
BROWSE_REF	string	internal use, do not modify
DEDUPE_REF	string	internal use, do not modify
COADSF	integer	internal use, do not modify
IMPORT_REF	string	internal use, do not modify
PAFFLAGS	integer	internal use, do not modify
NLFREQ	integer	internal use, do not modify
NLCLASS	string	internal use, do not modify
PAFAGENTID	string	internal use, do not modify
PAFADMINID	string	internal use, do not modify
NLBUYER	string	internal use, do not modify
NLMAILZIP	string	internal use, do not modify
BCCMUPC	integer	internal use, do not modify
NLIDB	boolean	internal use, do not modify
PROOF_REF	string	internal use, do not modify

Records

A records collection is associated with an address table and represents the underlying database.

Record

A record represents a row in the underlying database. Its properties correspond to the fields in the database.

A record has an auto-generated bookmark.

Indexes

An indexes collection is associated with an address table.

The default index for an address table is identified by the INDEXNAME property of the address table.

Index

An index represents an index of the underlying database table associated with an address table.

An index can be referenced by the index property of a request for the following services.

• addressTableExport
• addressTableModify

An index has the following properties:

The id, name and expression properties are required. The id property is auto-generated and read only.

Name	Type	Description
id	string	Unique identifier
name	string	Name
expression	string	Database expression
unique	boolean	true if the index is unique, false if it allows non-unique values
descending	boolean	true if the index is ascending, false if the index is descending

Layouts

Attention

resourceGet() is not implemented.

A layouts collection is associated with an address table.

The default layout for an address table is identified by the LAYOUT_ID property of the address table.

Layout

Attention

resourceDelete(), resourcePut() and resourceSet() are not implemented.

A layout defines information, not included in the database schema, about the fields in the underlying database table associated with an address table.

The most important properties of a field in a layout are as follows.

• name is the field name in the underlying database schema.
• displayName is the display name of a field.
• addressGroup is an integer that groups fields together (eg. 1 means "Main Address Group") and dataType is an integer that identifies the type of data in a field, beyond what is described by the database schema (eg. 7 means "City").

Each valid integer value for the addressGroup and dataType properties has alias string values (eg. "MAIN" or "City") that can be used instead in some cases. The addresstable.json file in the installation folder defines all valid integer and alias string values.

In the addresstable.json file, the code property of an item in the addressGroups or dataTypes array in this file defines a regular expression that a string value must satisfy in order for it to be a valid alias for the value indicated by the id property. For example, this hypothetical snippet from the file would mean that the valid alias string values for an integer value of 987 are "EX" or "Example".

{
  "id":987,
  "displayName":"Example",
  "code":"^(EX|Example)$"
}

The following services can use alias string values and can reference a field by name, displayName or a combination of addressGroup and dataType.

• addressTableCreateFromTemplate
• addressTableExport
• addressTableImport
• addressTableModify

The callResource-addressTables service does not allow alias string values.

A layout has the following properties:

The id and name properties are required. The id property is auto-generated and read only.

Name	Type	Description
id	string	Unique identifier
name	string	Name
LIST_ID	string	internal use, do not modify
LAYOUTTYPE	string	internal use, do not modify
FORM_WIDTH	float	internal use, do not modify
FORM_HT	float	internal use, do not modify
AUTOZIP4	boolean	internal use, do not modify
COMPONENTS	string	internal use, do not modify
VERSION	string	internal use, do not modify
MEMOTEXT	string	internal use, do not modify
└ fields	array	internal use, do not modify
id	string	Unique identifier
name	string	Name of the field
displayName	string	Display name of the field
addressGroup	integer	Address group of the field
dataType	integer	Data type of the field
SEQ_NO	string	internal use, do not modify
EDIT_MASK	string	internal use, do not modify
LEFT	integer	internal use, do not modify
TOP	integer	internal use, do not modify
WIDTH	integer	internal use, do not modify
HEIGHT	integer	internal use, do not modify
FONTFACE	string	internal use, do not modify
FONTSIZE	integer	internal use, do not modify
FONTSTYLE	string	internal use, do not modify
SCRFLDTYPE	integer	internal use, do not modify
COMPONENTS	string	internal use, do not modify
LOOKUPTBNR	integer	internal use, do not modify
ISCALCFLD	boolean	internal use, do not modify
VALUETRUE	string	internal use, do not modify
VALUEFALSE	string	internal use, do not modify
DISPFMT	string	internal use, do not modify
EDITFMT	string	internal use, do not modify
MAXVAL	string	internal use, do not modify
MINVAL	string	internal use, do not modify

Selectivities

A selectivities collection is associated with an address table.

The default selectivity for an address table is identified by the SEL_ID property of the address table.

Selectivity

A selectivity is a filter for the underlying database table associated with an address table.

A selectivity can be referenced by the selectivity property of a request for the following service.

• addressTableExport
• addressTableModify
• presort

A selectivity has the following properties:

The id and name properties are required. The id property is auto-generated and read only.

Name	Type	Description
id	string	Unique identifier
name	string	Name
expression	string	Boolean expression null = No filter by expression
sampleInterval	integer	+ = Interval for sampling one record per interval - = Interval for sampling all but one record per interval null = No sampling per interval
sampleRandom	float	Probability of a record being sampled at random, 0 to 1 null = No random sampling
sampleMaximum	integer	Maximum records null = No maximum records

Company Catalog

The company catalog is a collection of companies.

Company

A company can be referenced by the following properties:

• The AGENTID property of a permit
• The HOLDERID property of a permit
• The PREPAREID property of a permit
• The MAILID property of a publication
• The PERMITID property of a publication
• The PUBLISHID property of a publication

A company has the following properties:

The id and name properties are required. The id property is auto-generated and read only.

Name	Type	Description
id	string	Unique identifier
name	string	Name
ALTADDR	string	Alternate address
ADDRESS	string	Delivery address
CITY	string	City
STATE	string	State
ZIP	string	ZIP+4
PHONE	string	Phone number
FAX	string	Fax number
EMAIL	string	Email address
DUNBRAD	string	Dun & Bradsheet number
CTASID	string	CAPS ID
NONPROF	boolean	Authorized for non-profit mailing
COUNTRY	string	County
FZIP	string	Postal code
TAXID	string	internal use, do not modify
PERNUM	string	internal use, do not modify
PERTYPE	integer	internal use, do not modify
FACC	string	FACC
EXT	string	Phone extension
CONTACT	string	Contact
NPNUMBER	string	Non-profit number
PAFCONTACT	string	internal use, do not modify
PAFTITLE	string	internal use, do not modify
NAICS	string	internal use, do not modify
PARENTNAME	string	internal use, do not modify
ALTNAME	string	internal use, do not modify
MAILERID	string	Mailer ID
CRID	string	CRID
WEBSITE	string	internal use, do not modify
IDENTIFIER	string	User-defined text, intended for identification
PAYACCTNO	string	Payment account number

Permit Catalog

The permit catalog is a collection of permits.

Permit

A permit represents a USPS mailing permit.

A permit can be referenced by the following properties:

• The PERMITID property of a publication
• The permit property of a request for the eSubmission or mailDat service
• The permit property of a request for the presort service

A permit has the following properties:

The id and name properties are required. The id property is auto-generated and read only.

Name	Type	Description
id	string	Unique identifier
name	string	Name
PERMITNO	string	Permit number
MAILINGPO	string	Permit post office of mailing
PERMITNAME	string	Name of the permit
PREPNAME	string	Name of the prepared-for company
HOLDERID	string	id of the permit holder in the company catalog
PREPAREID	string	id of the prepared-for company in the company catalog
AGENTID	string	id of the mailing agent in the company catalog
PERMITTYPE	integer	Type of permit 1 = Permit 2 = Meter 3 = Stamp 4 = Government Permit 6 = Periodicals Pending 7 = Government Meter
PAYACCTNO	string	Payment account number
HOLDERNAME	string	Name of the permit holder

Publication Catalog

The publication catalog is a collection of publications.

Publication

A publication represents information required by the USPS when mailing a publication.

A publication can be referenced by the following properties:

• The publicationNumber property of a request for the eSubmission or mailDat service
• The publication property of a request for the presort service

A publication has the following properties:

The id and name properties are required. The id property is auto-generated and read only.

Name	Type	Description
id	string	Unique identifier
name	string	Name
PUBNAME	string	Publication name
PUBNO	string	Publication number
EDCODE	string	Edition code
ISSUEDATE	string	Issue date
ISSUEFREQ	string	Issue frequency
CUSTNO	string	Publisher Dun & Bradsteet number
PHONE	string	Publisher phone number
MAILID	string	id of the mailing agent in the company catalog
CONTCNTY	string	Contiguous county
EMAIL	string	Publisher email address
EXT	string	Publisher phone extension
PERMITID	string	id of the pending periodicals permit in the permit catalog
MAILINGPO	string	Entry post office
CONTACT	string	Publisher contact
PUBLISHID	string	id of the publisher in the company catalog
PAYACCTNO	string	Payment account number