Overview

This documentation provides a comprehensive guide to the various objects used in our API. Each object is detailed with its attributes, types, requirements, and examples to help developers understand and implement them effectively. Below is the Table of Contents for quick navigation:

ACH Object: Detailed information about the ACH (Automated Clearing House) object, including attributes and usage.
Address Object: Specifications for the address object, used to capture address details.
Counterparty Address Object: Information on the address of the business or individual who owns the external account.
Counterparty Bank Address Object: Details about the address of the counterparty's bank.
Details Object: Attributes and examples for the object containing customer identifying information.
Instant Payment Object: Information on instant payment details, including transmitter information.
Intermediary Bank Address Object: Specifications for the address of the intermediary bank involved in wire transfers.
Shipping Address Object: Details for specifying the shipping address for physical debit cards.
Wire Object: Comprehensive guide to wire-specific information, including intermediary bank and transmitter details.
Wire Transmitter Object: Attributes and examples for the address of the wire transmitter.
Option 1: Specifications for the first optional address format.
Option 2: Specifications for the second optional address format.

Each section provides detailed descriptions, validation rules, and example values to ensure accurate implementation and usage. This guide aims to facilitate a smooth integration process and enhance the overall developer experience.

ACH Object

Description:
The ACH object specifies details for ACH transactions and returns.

Attribute	Type	Required	Description	Example
`originator_name`	string	required	Individual or business originating the ACH transfer. 1 to 16 characters; letters, numbers, apostrophe, comma, period, dash allowed.	"J. Fred Muggs"
`company_id`	string	required	ACH Company ID. 1 to 10 characters. Letters, numbers, apostrophe, comma, period, dash allowed.	"ABC-123456"
`company_discretionary_data`	string	optional	An optional field to add customized information such as a customer code or internal reference number. 1 to 20 characters. Alphanumeric. Also allows '.', '#', or '-'.	"#ABC.123"
`prenote`	boolean	optional	If prenote is 'true' the amount of the transfer must be $0.00. Newline will infer credit_prenote or debit_prenote based on the source and destination accounts. If prenote is 'true' then the Transaction Type of the resulting transaction record is of type: "prenote". If no value is provided, the default value will be 'false'.	true
`sec_code`	string	required	Standard Entry Class (SEC) code. Newline supports the following SEC codes: CCD, CIE, PPD, TEL, WEB. For more details, refer to our ACH guide's section on SEC code use.	"CIE"
`entry_description`	string	required	Description value that will appear in the bank statement.	"B1-A2-C3"
`service_processing`	string	required	Requested service processing duration for the ACH transfer. Allowable values are: STANDARD or SAMEDAY	"STANDARD"
`effective_entry_date`	string	required	The effective date when the transaction is scheduled to be processed. Date values provided cannot be in the past or provided in the future beyond 30 days. For received returns, if the date provided by the originating financial institution does not match the Newline format, then the raw value will be returned. The Newline date format is YYYY-MM-DD	"2023-12-01"
`id_number`	string	optional	Unique identifier supplied by the originator of a transaction (e.g. invoice number). 1 to 22 characters depending on SEC code, alphanumeric. If the SEC value is anything other than CIE, then this is an optional field and can be up to 15 characters. If SEC value CIE is provided, then the ID number is mandatory, and the character length can be up to 22 characters.	"4270465600"
`addenda`	string	optional	Optional additional payment-related information, such as invoice numbers, originator/receiver information, payment instructions, etc. Up to 80 characters. Optional for all Newline supported SEC codes other than TEL. Newline will reject the Transfer if an Addenda value is provided with SEC code TEL.

Relevant Endpoints:

Address Object

Description:
The address object specifies address details for various entities.

Attribute	Type	Required	Description	Example
street1	string \| null	required	Maximum 35 characters	"123 Abc St."
street2	string \| null		Maximum 35 characters	"Suite 4A"
city	string \| null	required	Maximum 35 characters	"Chicago"
state	string \| null	required	2 characters. Must be a valid US state abbreviation.	"IL"
postal_code	string \| null	required	5-digit string. ZIP+4 is allowed.	"60301"

Relevant Endpoints:

Adjust Customer Data

Counterparty Address Object

Description:
The counterparty address object specifies address details for counterparties in transactions.

Attribute	Type	Required	Description	Example
street_number	number	required	Building number for counterparty address. Numbers only.	1234
street1	string	required	Street name for counterparty address. Length ≤ 70.	"Abc St."
street2	string	optional	Optional second line of street. Length ≤ 70.	"Suite 4A"
city	string \| null	required	Maximum 35 characters	"Chicago"
state	string \| null	required	2 characters. Must be a valid US state abbreviation.	"IL"
postal_code	string \| null	required	5-digit string. ZIP+4 is allowed.	"60301"
country	string \| null	required	2 character ISO 3166 country code.	"US"

Relevant Endpoints:

Counterparty Bank Address Object

Description:
The counterparty bank address object specifies address details for the bank associated with a counterparty.

Attribute	Type	Required	Description	Example
line1	string \| null	optional	Optional 35 characters. Cannot contain # @ $ ! ” % & * ; < > { } [ ] _ ^ \ ~	"123 Abc St."
line2	string \| null	optional	Optional 35 characters. Cannot contain # @ $ ! ” % & * ; < > { } [ ] _ ^ \ ~	"Boring, Oregon 97009"
line3	string \| null	optional	Optional 32 characters. Note that this length is shorter than the other lines. Cannot contain # @ $ ! ” % & * ; < > { } [ ] _ ^ \ ~	"Boston, MA 02110"
country	string \| null	required	2 character ISO 3166 country code.	"US"

Relevant Endpoints:

Details Object

Description:
The details object specifies personal details for customers.

Attribute	Type	Required	Description	Example
first_name	string \| null		1-40 characters	"Olive"
middle_name	string \| null		1-40 characters	"Olivia"
last_name	string \| null		1-40 characters	"Oyl"
suffix	string \| null		1-30 characters	"Jr."
phone	string \| null		Exactly 10 digits long (no hyphens, parentheses, or spaces)	"5555551212"
business_name	string \| null		Required for customers of type sole_proprietor and discarded otherwise. 1-256 alphanumeric characters.	"Oliver's Olive Emporium"
ssn	string \| null		Follows pattern 'ddd-dd-dddd'. Required for primary or sole_proprietor customers.	"111-22-3333"
dob	date \| null		Follows pattern 'YYYY-MM-DD'	"1919-12-08"
address	object		An object containing the supplied identifying information for the Customer
street1	string \| null	required	Maximum 35 characters	"123 Abc St."
street2	string \| null	required	Maximum 35 characters	"Suite 4A"
city	string \| null	required	Maximum 35 characters	"Chicago"
state	string \| null	required	2 characters. Must be a valid US state abbreviation.	"IL"
postal_code	string \| null	required	5-digit string. ZIP+4 is allowed.	"60301"

Relevant Endpoints:

Instant Payment Object

Description:
The instant payment object specifies details for initiating an instant payment.

Attribute	Type	Required	Description	Example
instant_payment	object		Instant payment information. Only present if the Transfer is an instant payment.
instant_payment_transmitter	object		Address of the Transmitter. To be populated if the initiator_type is Transmitter.
name	string	required	Name of the Transmitter. Length ≤ 35.	"Marge's Roofing Inc"
transmitter_identifier	string	required	Up to 24 characters, and supplied by Transmitter. Alphanumeric only. Length between 1 and 24.	"123456789012ABC"
street_number	number	required	Building number for Transmitter address. Numbers only.	1234
street1	string	required	Street name for Transmitter address. Length ≤ 70.	"Abc St."
street2	string	optional	Optional second line of street. Length ≤ 70.	"Suite 4A"
city	string \| null	required	Maximum 35 characters	"Chicago"
state	string \| null	required	2 characters. Must be a valid US state abbreviation.	"IL"
postal_code	string \| null	required	5-digit string. ZIP+4 is allowed.	"60301"
country	string \| null	required	2 character ISO 3166 country code.	"US"

Relevant Endpoints:

Intermediary Bank Address Object

Description:
The intermediary bank address object specifies address details for intermediary banks in wire transactions.

Attribute	Type	Required	Description	Example
instant_payment	object		Instant payment information. Only present if the Transfer is an instant payment.
instant_payment_transmitter	object		Address of the Transmitter. To be populated if the initiator_type is Transmitter.
name	string	required	Name of the Transmitter. Length ≤ 35.	"Marge's Roofing Inc"
transmitter_identifier	string	required	Up to 24 characters, and supplied by Transmitter. Alphanumeric only. Length between 1 and 24.	"123456789012ABC"
street_number	number	required	Building number for Transmitter address. Numbers only.	1234
street1	string	required	Street name for Transmitter address. Length ≤ 70.	"Abc St."
street2	string	optional	Optional second line of street. Length ≤ 70.	"Suite 4A"
city	string \| null	required	Maximum 35 characters	"Chicago"
state	string \| null	required	2 characters. Must be a valid US state abbreviation.	"IL"
postal_code	string \| null	required	5-digit string. ZIP+4 is allowed.	"60301"
country	string \| null	required	2 character ISO 3166 country code.	"US"

Relevant Endpoints:

Shipping Address Object

Description:
The shipping address object specifies the address for shipping a physical debit card.

Attribute	Type	Required	Description	Example
street1	string	required	4-40 characters. Cannot be a P.O. Box.	"123 Abc St."
street2	string \| null	optional	Maximum 30 characters	"Apt 2"
city	string	required	Maximum 30 characters	"Chicago"
state	string	required	2 characters. Must be a valid US state abbreviation.	"IL"
postal_code	string	required	5-digit string. ZIP+4 allowed.	"12345"

Relevant Endpoints:

Wire Object

Description:
The wire object specifies details for wire transactions and returns.

Attribute	Type	Required	Description	Example
intermediary_bank_address	object		Address of the intermediary bank. To be populated if an intermediary bank is required to execute the wire transfer.
line1	string \| null	optional	Optional 35 characters. Cannot contain # @ $ ! ” % & * ; < > { } [ ] _ ^ \ ~	"123 Abc St."
line2	string \| null	optional	Optional 35 characters. Cannot contain # @ $ ! ” % & ; < > { } [ ] ^ \ ~	"Boring, Oregon 97009"
line3	string \| null	optional	Optional 32 characters. Note that this length is shorter than the other lines. Cannot contain # @ $ ! ” % & ; < > { } [ ] ^ \ ~	"CA 94016"
country	string \| null	required	2 character ISO 3166 country code.	"US"
intermediary_bank_name	string		Length ≤ 35	"Fidelity Fiduciary Bank"
intermediary_bank_routing_number	string		Length between 9 and 9. The ABA routing number associated with the intermediary bank involved in the wire transfer. This value is required if intermediary_bank_name or intermediary_bank_address is present; optional otherwise	"923456789"
wire_instructions	string		Length ≤ 140. Additional details or instructions for the wire, issued to the recipient financial institution when the wire is executed.	"Send ASAP"
wire_transmitter	object		Address of the Transmitter. To be populated if the initiator_type is Transmitter.
name	string	required	Length ≤ 35. Name of the Transmitter.	"Marge's Roofing Inc"
transmitter_identifier	string	required	Length between 1 and 24. Up to 24 characters, and supplied by Transmitter. Alphanumeric only.	"123456789012ABC"
line1	string \| null	required	Up to 35 characters. Cannot contain # @ $ ! ” % & * ; < > { } [ ] _ ^ \ ~	"123 Abc St."
line2	string \| null	optional	Optional 35 characters. Cannot contain # @ $ ! ” % & ; < > { } [ ] ^ \ ~	"Boring, Oregon 97009"
line3	string \| null	optional	Optional 32 characters. Note that this length is shorter than the other lines. Cannot contain # @ $ ! ” % & ; < > { } [ ] ^ \ ~	"CA 94016"
country	string	required	Length between 2 and 2. 2 character ISO 3166 country code.	"US"

Relevant Endpoints:

Wire Transmitter Object

Description:
The wire transmitter object specifies the address details for the transmitter. This information is required if the initiator_type is Transmitter.

Attribute	Type	Required	Description	Example
name	string	required	Length ≤ 35. Name of the Transmitter.	"Marge's Roofing Inc"
transmitter_identifier	string	required	Length between 1 and 24. Up to 24 characters, and supplied by Transmitter. Alphanumeric only.	"123456789012ABC"
line1	string \| null	required	Up to 35 characters. Cannot contain # @ $ ! ” % & * ; < > { } [ ] _ ^ \ ~	"123 Abc St."
line2	string \| null	optional	Optional 35 characters. Cannot contain # @ $ ! ” % & ; < > { } [ ] ^ \ ~	"Boring, Oregon 97009"
line3	string \| null	optional	Optional 32 characters. Note that this length is shorter than the other lines. Cannot contain # @ $ ! ” % & ; < > { } [ ] ^ \ ~	"CA 94016"
country	string	required	Length between 2 and 2. 2 character ISO 3166 country code.	"US"

Relevant Endpoints:

Initiate a Transfer

Option 1

Description:
Option 1 encapsulates address details for a transaction simulation.

Attribute	Type	Required	Description	Example
line1	string \| null	optional	Optional 35 characters. Cannot contain # @ $ ! ” % & ; < > { } [ ] ^ \ ~	"123 Abc St."
line2	string \| null	optional	Optional 35 characters. Cannot contain # @ $ ! ” % & ; < > { } [ ] ^ \ ~	"Boring, Oregon 97009"
line3	string \| null	optional	Optional 32 characters. Note that this length is shorter than the other lines. Cannot contain # @ $ ! ” % & * ; < > { } [ ] _ ^ \ ~
country	string \| null	required	2 character ISO 3166 country code.	"US"

Relevant Endpoints:

Simulate a Transaction

Option 2

Description:
Option 2 encapsulates detailed address and counterparty information for a transaction simulation.

Attribute	Type	Required	Description	Example
street_number	number	required	Building number for counterparty address. Numbers only.	1234
street1	string	required	Length ≤ 70. Street name for counterparty address.	"Abc St."
street2	string	optional	Length ≤ 70. Optional second line of street.	"Suite 4A"
city	string \| null	required	Maximum 35 characters	"Chicago"
state	string \| null	required	2 characters. Must be a valid US state abbreviation.	"IL"
postal_code	string \| null	required	5-digit string. ZIP+4 is allowed.	"60301"
country	string \| null	required	2 character ISO 3166 country code.	"US"