Developers
Applications API for ACHQ partners.
Send merchant applications to ACHQ straight from your own software. One HTTPS call, the same review as our online application, and every merchant is credited to you automatically.
curl -X POST https://www.achq.com/api/v1/applications \
-H "Authorization: Bearer achq_test_..." \
-H "Content-Type: application/json" \
-d @application.json
HTTP/1.1 201 Created
{
"id": "a0UPj00000EXAMPLE",
"status": "received",
"test": true
}What it is
The Applications API is for ACHQ referral and ISO partners who want to submit merchant applications from their own software instead of sending merchants to the online form at achq.com/apply.
It takes the same fields as the online application and runs the same checks and the same underwriting. Each API key belongs to one partner, so every application you send is credited to you in our system. You never need to send a partner code.
After you submit, ACHQ emails the merchant to confirm, and our team picks up the application from there. Bank account verification and any follow-up go to the merchant directly.
Authentication
Send your API key in the Authorization header as a Bearer token on every request.
Authorization: Bearer achq_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- Live keys start with
achq_live_and create real applications. - Test keys start with
achq_test_and create practice records only. See Test keys. - Call the API from your server only. Never put a key in a web page, mobile app or anything a merchant can see. If a key leaks, email us and we will turn it off and issue a new one.
Endpoint
- Body: one JSON object with the fields below. Header
Content-Type: application/json. - One application per request. Submit one merchant at a time.
- Any
partnerfield in the body is ignored. Credit always comes from the key.
Fields
This table is built from the same rules the API checks, so it always matches what the API accepts. Unknown fields are ignored. Booleans must be JSON true or false, and numbers must be JSON numbers, not strings.
Business
legalbusinessname
string · Required: Yes
Legal business name as registered with the IRS. Up to 100 characters.
dba
string · Required: No
Doing business as name, if different from the legal name. Up to 100 characters.
tax_id
string · Required: Yes
EIN, 9 digits. Dashes are fine and are stripped.
business_type
string · Required: Yes
Legal structure of the business.
CorporationLLCSole ProprietorPartnershipNon-Profitsector
string · Required: Yes
Industry category.
Digital Goods and SoftwareeCommerce and RetailEducationEntertainment And RecreationFinancial ServicesGeneral Building ServicesMedical ServicesMembership OrganizationsPersonal ServicesProfessional ServicesTravel / LodgingUtilitiesTransportation and Facilitiesspecific_industry
string · Required: No
Free text, for example "Bookkeeping" or "HVAC repair". Up to 100 characters.
business_description
string · Required: Yes
What the business sells and to whom. Up to 255 characters.
service_use
string · Required: No
How the merchant plans to use ACH. Defaults to business_description. Up to 255 characters.
website
string · Required: Yes
Business website. "https://" is added if missing. Up to 255 characters.
primary_phone
string · Required: Yes
Business phone, 10 to 15 digits. Any formatting is fine. Up to 40 characters.
year_started
integer · Required: No
Year the business started, for example 2019. Not in the future.
Business address
business_street
string · Required: Yes
Street address. Up to 120 characters.
business_street2
string · Required: No
Suite, unit or floor. Up to 120 characters.
business_city
string · Required: Yes
City. Up to 80 characters.
business_state
string · Required: Yes
Two-letter state code.
51 allowed values
AL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY
business_zip
string · Required: Yes
ZIP or ZIP+4, for example 80003 or 80003-1234. Up to 10 characters.
state_of_registration
string · Required: Yes
State where the business is registered, two-letter code.
51 allowed values
AL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY
Beneficial owner
ownerFirstName
string · Required: Yes
Owner first name. Up to 50 characters.
ownerLastName
string · Required: Yes
Owner last name. Up to 50 characters.
owner_title
string · Required: No
Owner title, for example "Owner" or "CEO". Up to 80 characters.
owner_email
string · Required: Yes
Owner email. ACHQ sends the application confirmation here. Up to 254 characters.
owner_cell
string · Required: Yes
Owner mobile phone, 10 to 15 digits. Up to 40 characters.
owner_dob
string · Required: Yes
Date of birth as YYYY-MM-DD. The owner must be 18 or older.
owner_street
string · Required: Yes
Owner home street address. Up to 120 characters.
owner_city
string · Required: Yes
Owner home city. Up to 80 characters.
owner_state
string · Required: Yes
Owner home state, two-letter code.
51 allowed values
AL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY
owner_zip
string · Required: Yes
Owner home ZIP. Up to 10 characters.
owner_ssn_last4
string · Required: Yes
Last 4 digits of the owner SSN. Never send the full SSN.
Volume
charge_dollars
number · Required: When add_charges is true
Expected monthly dollar volume of charges. Must be greater than zero.
charge_count
integer · Required: When add_charges is true
Expected number of charges per month. Whole number, greater than zero.
charge_max
number · Required: When add_charges is true
Largest single charge in dollars. Must be greater than zero.
payout_dollars
number · Required: When add_payouts is true
Expected monthly dollar volume of payouts. Must be greater than zero.
payout_count
integer · Required: When add_payouts is true
Expected number of payouts per month. Whole number, greater than zero.
payout_max
number · Required: When add_payouts is true
Largest single payout in dollars. Must be greater than zero.
add_charges
boolean · Required: Yes
true if the merchant will pull money from customers. At least one of add_charges or add_payouts must be true.
add_payouts
boolean · Required: Yes
true if the merchant will send money to customers or vendors.
Customers and authorization
person_customer
boolean · Required: Yes
true if the merchant charges consumers (PPD). At least one customer type must be true.
business_customer
boolean · Required: Yes
true if the merchant charges businesses (CCD).
web_auth
boolean · Required: Yes
true if customers authorize payments online. At least one authorization method must be true.
signed_auth
boolean · Required: Yes
true if customers sign a written authorization.
phone_auth
boolean · Required: Yes
true if customers authorize payments by phone.
Customer service
statement_descriptor
string · Required: Yes
Name shown on the customer bank statement. Up to 10 characters: uppercase letters, numbers, spaces and . & - only. Up to 10 characters.
service_phone
string · Required: Yes
Phone number customers call with questions. Up to 40 characters.
service_email
string · Required: Yes
Email address customers write to with questions. Up to 254 characters.
refund_policy
string · Required: No
Refund policy text or a link to it. Up to 2000 characters.
Banking
transfer_name
string · Required: Yes
Name of the bank where ACHQ settles funds. Up to 80 characters.
transfer_routing
string · Required: Yes
9-digit ABA routing number. Must pass the ABA checksum.
transfer_account
string · Required: Yes
Settlement account number, 4 to 20 digits. Up to 20 characters.
billing_choice
boolean · Required: Yes
true to pay ACHQ fees from the settlement account. false to use a separate billing account below.
billing_name
string · Required: When billing_choice is false
Billing bank name. Up to 80 characters.
billing_routing
string · Required: When billing_choice is false
Billing 9-digit ABA routing number.
billing_account
string · Required: When billing_choice is false
Billing account number, 4 to 20 digits.
Consent
consent
boolean · Required: Yes
Must be true. Send it only after the merchant has agreed to the ACHQ Terms of Service and Privacy Policy at achq.com/legal.
Other
source
string · Required: No
Optional free text that shows up for the ACHQ team, for example your own reference for the merchant. Up to 120 characters.
| Field | Type | Required | Notes |
|---|---|---|---|
| Business | |||
| legalbusinessname | string | Yes | Legal business name as registered with the IRS. Up to 100 characters. |
| dba | string | No | Doing business as name, if different from the legal name. Up to 100 characters. |
| tax_id | string | Yes | EIN, 9 digits. Dashes are fine and are stripped. |
| business_type | string | Yes | Legal structure of the business.CorporationLLCSole ProprietorPartnershipNon-Profit |
| sector | string | Yes | Industry category.Digital Goods and SoftwareeCommerce and RetailEducationEntertainment And RecreationFinancial ServicesGeneral Building ServicesMedical ServicesMembership OrganizationsPersonal ServicesProfessional ServicesTravel / LodgingUtilitiesTransportation and Facilities |
| specific_industry | string | No | Free text, for example "Bookkeeping" or "HVAC repair". Up to 100 characters. |
| business_description | string | Yes | What the business sells and to whom. Up to 255 characters. |
| service_use | string | No | How the merchant plans to use ACH. Defaults to business_description. Up to 255 characters. |
| website | string | Yes | Business website. "https://" is added if missing. Up to 255 characters. |
| primary_phone | string | Yes | Business phone, 10 to 15 digits. Any formatting is fine. Up to 40 characters. |
| year_started | integer | No | Year the business started, for example 2019. Not in the future. |
| Business address | |||
| business_street | string | Yes | Street address. Up to 120 characters. |
| business_street2 | string | No | Suite, unit or floor. Up to 120 characters. |
| business_city | string | Yes | City. Up to 80 characters. |
| business_state | string | Yes | Two-letter state code.51 allowed valuesAL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY |
| business_zip | string | Yes | ZIP or ZIP+4, for example 80003 or 80003-1234. Up to 10 characters. |
| state_of_registration | string | Yes | State where the business is registered, two-letter code.51 allowed valuesAL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY |
| Beneficial owner | |||
| ownerFirstName | string | Yes | Owner first name. Up to 50 characters. |
| ownerLastName | string | Yes | Owner last name. Up to 50 characters. |
| owner_title | string | No | Owner title, for example "Owner" or "CEO". Up to 80 characters. |
| owner_email | string | Yes | Owner email. ACHQ sends the application confirmation here. Up to 254 characters. |
| owner_cell | string | Yes | Owner mobile phone, 10 to 15 digits. Up to 40 characters. |
| owner_dob | string | Yes | Date of birth as YYYY-MM-DD. The owner must be 18 or older. |
| owner_street | string | Yes | Owner home street address. Up to 120 characters. |
| owner_city | string | Yes | Owner home city. Up to 80 characters. |
| owner_state | string | Yes | Owner home state, two-letter code.51 allowed valuesAL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY |
| owner_zip | string | Yes | Owner home ZIP. Up to 10 characters. |
| owner_ssn_last4 | string | Yes | Last 4 digits of the owner SSN. Never send the full SSN. |
| Volume | |||
| charge_dollars | number | When add_charges is true | Expected monthly dollar volume of charges. Must be greater than zero. |
| charge_count | integer | When add_charges is true | Expected number of charges per month. Whole number, greater than zero. |
| charge_max | number | When add_charges is true | Largest single charge in dollars. Must be greater than zero. |
| payout_dollars | number | When add_payouts is true | Expected monthly dollar volume of payouts. Must be greater than zero. |
| payout_count | integer | When add_payouts is true | Expected number of payouts per month. Whole number, greater than zero. |
| payout_max | number | When add_payouts is true | Largest single payout in dollars. Must be greater than zero. |
| add_charges | boolean | Yes | true if the merchant will pull money from customers. At least one of add_charges or add_payouts must be true. |
| add_payouts | boolean | Yes | true if the merchant will send money to customers or vendors. |
| Customers and authorization | |||
| person_customer | boolean | Yes | true if the merchant charges consumers (PPD). At least one customer type must be true. |
| business_customer | boolean | Yes | true if the merchant charges businesses (CCD). |
| web_auth | boolean | Yes | true if customers authorize payments online. At least one authorization method must be true. |
| signed_auth | boolean | Yes | true if customers sign a written authorization. |
| phone_auth | boolean | Yes | true if customers authorize payments by phone. |
| Customer service | |||
| statement_descriptor | string | Yes | Name shown on the customer bank statement. Up to 10 characters: uppercase letters, numbers, spaces and . & - only. Up to 10 characters. |
| service_phone | string | Yes | Phone number customers call with questions. Up to 40 characters. |
| service_email | string | Yes | Email address customers write to with questions. Up to 254 characters. |
| refund_policy | string | No | Refund policy text or a link to it. Up to 2000 characters. |
| Banking | |||
| transfer_name | string | Yes | Name of the bank where ACHQ settles funds. Up to 80 characters. |
| transfer_routing | string | Yes | 9-digit ABA routing number. Must pass the ABA checksum. |
| transfer_account | string | Yes | Settlement account number, 4 to 20 digits. Up to 20 characters. |
| billing_choice | boolean | Yes | true to pay ACHQ fees from the settlement account. false to use a separate billing account below. |
| billing_name | string | When billing_choice is false | Billing bank name. Up to 80 characters. |
| billing_routing | string | When billing_choice is false | Billing 9-digit ABA routing number. |
| billing_account | string | When billing_choice is false | Billing account number, 4 to 20 digits. |
| Consent | |||
| consent | boolean | Yes | Must be true. Send it only after the merchant has agreed to the ACHQ Terms of Service and Privacy Policy at achq.com/legal. |
| Other | |||
| source | string | No | Optional free text that shows up for the ACHQ team, for example your own reference for the merchant. Up to 120 characters. |
Example
Every value below is a placeholder. Use real merchant details with a live key, or any values that pass the field rules with a test key.
curl -X POST https://www.achq.com/api/v1/applications \
-H "Authorization: Bearer $ACHQ_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f6c1d2e-8b7a-4c5d-9e0f-1a2b3c4d5e6f" \
-d @application.json{
"legalbusinessname": "Example Plumbing LLC",
"dba": "Example Plumbing",
"tax_id": "00-0000001",
"business_type": "LLC",
"sector": "General Building Services",
"specific_industry": "Plumbing",
"business_description": "Residential plumbing repair. Customers pay invoices by bank transfer.",
"website": "https://example.com",
"primary_phone": "(555) 555-0100",
"year_started": 2015,
"business_street": "100 Example St",
"business_city": "Denver",
"business_state": "CO",
"business_zip": "80202",
"state_of_registration": "CO",
"ownerFirstName": "Jane",
"ownerLastName": "Example",
"owner_title": "Owner",
"owner_email": "jane@example.com",
"owner_cell": "(555) 555-0101",
"owner_dob": "1980-01-01",
"owner_street": "200 Example Ave",
"owner_city": "Denver",
"owner_state": "CO",
"owner_zip": "80202",
"owner_ssn_last4": "0000",
"add_charges": true,
"add_payouts": false,
"charge_dollars": 25000,
"charge_count": 100,
"charge_max": 1500,
"person_customer": true,
"business_customer": false,
"web_auth": true,
"signed_auth": false,
"phone_auth": false,
"statement_descriptor": "EXAMPLE",
"service_phone": "(555) 555-0102",
"service_email": "support@example.com",
"refund_policy": "Refunds within 30 days on request.",
"transfer_name": "Example Bank",
"transfer_routing": "000000000",
"transfer_account": "0000000000",
"billing_choice": true,
"consent": true
}{
"id": "a0UPj00000EXAMPLE",
"status": "received",
"test": false
}Responses and error codes
Every response is JSON. Error bodies never include merchant data.
| Status | What it means | Body |
|---|---|---|
| 201 | Application received. Keep the id for your records. | { "id": "a0UPj00000EXAMPLE", "status": "received", "test": false } |
| 400 | A field is missing or invalid. fields lists every problem by field name. Fix them and send again. | { "error": "validation_error", "fields": { "tax_id": ["Tax ID (EIN) must be 9 digits"] } } |
| 400 | The body is not valid JSON. | { "error": "invalid_json" } |
| 401 | The API key is missing, mistyped or turned off. | { "error": "unauthorized" } |
| 409 | The same application was already submitted in the last two minutes. id is the existing application. Nothing new was created. | { "error": "duplicate", "id": "a0UPj00000EXAMPLE", "status": "received", "test": false } |
| 409 | A request with the same Idempotency-Key is still running. Wait a few seconds and retry. | { "error": "request_in_progress" } |
| 429 | More than 30 requests in a minute from one key. Wait the number of seconds in the Retry-After header. | { "error": "rate_limited" } |
| 500 | Something went wrong on our side. Retry with the same Idempotency-Key, or email sales@achq.com if it keeps happening. | { "error": "server_error" } |
Test keys
Every partner gets a test key along with a live key. A test key runs the full request, including every field check, but the result is a practice record that is clearly marked as a test. No real merchant is created, no emails go out, and the response has "test": true.
Build and test with the test key, then switch to the live key when you are ready. Nothing else changes.
Idempotency
Send an Idempotency-Key header with a unique value for each application, such as a UUID. If a request times out or you are not sure it went through, send it again with the same key. For 10 minutes we return the first response instead of creating a second application, and the replay carries an Idempotent-Replayed: true header.
Keys are 8 to 128 characters: letters, numbers, dashes and underscores. Use a new key for every new application.
Rate limits
Each API key can send up to 30 requests per minute. Over that, the API returns 429 with a Retry-After header in seconds. If you need more, email us and tell us your expected volume.
Get an API key
API keys are for approved ACHQ referral and ISO partners. Email sales@achq.com with your company name and we will send you a live key and a test key. Not a partner yet? Start with the partner program. Looking for the payments API instead? See the developers page.

