NAV

Introduction

The ISO Amp API is a RESTful API for integrating with the ISO Amp tool. The examples use the domain example.com. Replace example.com with your ISO Amp domain.

Authentication

To authorize, use this code:

curl "api_endpoint_here" \
  -H "Authorization: 01234567890abcdef"

Make sure to replace 01234567890abcdef with your API key.

ISO Amp uses API keys to allow access to the API. You can register a API key in the admin panel.

ISO Amp expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: 01234567890abcdef

Merchant Application Integration

Proposals can be sent to your own backend system with a single click. Here is an example flow for a merchant application:

  1. User goes through quote tool and creates proposal.
  2. User clicks on "Start Application" button.
  3. The user's browser follows the link to your backend system and includes the proposal ID in the URL.
  4. Your backend system uses the proposal API to fetch the proposal.
  5. Your backend system creates a merchant services application with the relevant information from the proposal.
  6. Your backend system redirects the user's browser to the prefilled online application.

A proposal handoff link is the entity that creates a button on the proposal screen. The label of the button and the destination URL template is all that is required. Proposal handoff links are created in the Admin page in the Developer section.

Attribute Type Description
Agent View boolean Button will be displayed on the agent proposal view.
Label string The text of the button
Merchant View boolean Button will be displayed on the merchant proposal view.
URL Template string URL template for the destination of the button. {proposal_id} will be replaced with the actual proposal ID.

Statement Analysis

Submitting a statement for analysis is a 3-step process.

  1. Create the statement analysis request (POST /api/statement_analyses).
  2. Upload the statement file(s) (POST /api/statement_analyses/{id}/files).
  3. Start the statement analysis (POST /api/statement_analyses/{id}/start).

Create a Statement Analysis

curl https://example.com/api/statement_analyses \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{ "userId": 12345, "name": "Sept 2021", "merchantName": "Fancy Burgers" }'

The above command returns JSON structured like this:

{
  "id": "cc945b9a-47e5-4198-a3b8-b5ef1f6ed734"
}

HTTP Request

POST https://example.com/api/statement_analyses

Required Attributes

Attribute Type Description
userId int32 Analysis is for this user ID
name string Name for this statement analysis (e.g. the statement date)
merchantName string Name of business

Allowed Attributes

Attribute Type Default Description
notes string None Any extra notes to attach to this analysis

Upload a Statement File

After the statement analysis is created by the POST https://example.com/api/statement_analyses API the statement file(s) must be uploaded. The file contents must be the body of the POST. This API may be called multiple times to include multiple files (e.g. a processing statement and an American Express statement for the same month). Do not include multiple months or locations in the same analysis.

curl 'https://example.com/api/statement_analyses/0b8f40cb-9be1-4d93-8b2a-e36b97c4be45/files?filename=statement.pdf' \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/pdf' \
  -X POST \
  --data-binary @statement.pdf

The above command returns a 200 OK on success with no response body.

HTTP Request

POST https://example.com/api/statement_analyses/{id}/files

Required HTTP Headers

Header Description
Content-Length Size of uploaded file
Content-Type MIME type of uploaded file. Must be application/pdf.

Required Query Parameters

Attribute Type Description
filename string Name of uploaded file

Start statement analysis

After all required files have been uploaded this API should be called to start the statement analysis.

curl https://example.com/api/statement_analyses/0b8f40cb-9be1-4d93-8b2a-e36b97c4be45/start \
  -H 'Authorization: 01234567890abcdef' \
  -X POST

The above command returns a 202 Accepted on success with no response body.

HTTP Request

POST https://example.com/api/statement_analyses/{id}/start

Estimate Statement Summary

The estimate statement summary API can be used to quickly estimate fees from only a statement summary.

curl https://example.com/api/estimate_statement_summary \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{ "merchantActivity": [ {"type": "vs", "volume": 8000, "transactions": 100}, {"type": "mc", "volume": 2000, "transactions": 30} ], "totalCurrentFees": 320 }'

The above command returns JSON structured like this:

{"vmdInterchange":"151.49","vmdCardBrandFees":"4","amexOptBlue":null,"pinDebitNetworkFees":null,"scheduleACost":"14.6","margin":"0.01499"}

This endpoint estimates summary passthrough fees, processor costs, and markup.

HTTP Request

POST https://example.com/api/estimate_statement_summary

Request Attributes

Attribute Type Description
merchantActivity array of merchant activities List of merchant activities by card type and brand
totalCurrentFees numeric string Total fees the merchant is currently paying

Merchant Activity Attributes

Attribute Type Description
type string Type of activity
volume numeric string Volume of merchant activity in dollars
transactions integer Number of transactions

Merchant Activity Types

Type Description
vmd Visa, Mastercard, and Discover combined
vs Visa credit and check
vs_credit Visa credit
vs_check Visa check
mc Mastercard credit and check
mc_credit Mastercard credit
mc_check Mastercard check
ds Discover credit and check
ds_credit Discover credit
ds_check Discover check
amex American Express
pin_debit PIN Debit

Response Attributes

Attribute Type Description
vmdInterchange numeric string Estimated Visa, Mastercard, and Discover interchange fees
vmdCardBrandFees numeric string Estimated Visa, Mastercard, and Discover card brand fees
amexOptBlue numeric string Estimated American Express Opt Blue fees
pinDebitNetworkFees numeric string Estimated PIN debit network fees
scheduleACost numeric string Estimated Schedule A costs
margin numeric string Estimated margin rate

Proposals

Proposal Definition

Attribute Type Description
created_at timestamp When the user was created formatted in ISO8601
id uuid Unique identifier
merchant_activity array List of merchant activity records
program_features array List of selected program features
program_id uuid ID of the proposed program
proposed_fees array List of proposed fees
prospect_id uuid ID of the prospect this proposal belongs to

Merchant Activity Definition

Attribute Type Description
type string Type of activity (e.g. "Visa", "Mastercard", etc.)
volume numeric string Volume in dollars
transactions numeric string Number of transactions

Program Feature Definition

Attribute Type Description
id uuid Unique identifier
name string Name of program feature

Fee Definition

Attribute Type Description
name string Human-readable name of fee
internal_name string Name of fee designed for system integration
amount numeric string Amount of fee (unit depends on type of fee)
monthly_amount numeric string Monthly amount of fee in dollars based on merchant activity and selected program features

It is possible for there to a fee with a monthly_amount of 0 because of merchant activity or selected program features. For example, a monthly PIN debit fee with an amount of 9.95 may be present but have a monthly_amount of 0 if there are no PIN debit transactions.

Get All Proposals

curl "https://example.com/api/v1/proposals" \
  -H "Authorization: 01234567890abcdef"

The above command returns JSON structured like this:

{
  "object": "list",
  "data": [
    {
      "id": "64d569a7-1e77-4eb4-a1d8-37ed1a201a1b",
      "prospect_id": "d6fa9c24-a156-4083-9744-96626058329d",
      "created_at": "2019-03-26T01:46:57.532-04:00",
      "object": "proposal",
      "program_id": "06efac3f-5f48-4651-9048-1280f3dc1883",
      "merchant_activity": [
        {
          "type": "Visa",
          "volume": "2000.0",
          "transactions": "10.0"
        },
        {
          "type": "Mastercard",
          "volume": "0",
          "transactions": "0"
        },
        {
          "type": "Discover",
          "volume": "0",
          "transactions": "0"
        },
        {
          "type": "American Express",
          "volume": "0",
          "transactions": "0"
        },
        {
          "type": "PIN Debit",
          "volume": "0",
          "transactions": "0"
        }
      ],
      "program_features": [],
      "proposed_fees": [
        {
          "name": "VMD Volume",
          "internal_name": "vmd_volume",
          "amount": "0.0025",
          "monthly_amount": "5.0"
        },
        {
          "name": "VMD Per Item",
          "internal_name": "vmd_per_item",
          "amount": "0.08",
          "monthly_amount": "0.8"
        },
        {
          "name": "Monthly Fee",
          "internal_name": "monthly_fee",
          "amount": "9.95",
          "monthly_amount": "9.95"
        },
        {
          "name": "PCI Monthly",
          "internal_name": "pci_monthly",
          "amount": "9.95",
          "monthly_amount": "9.95"
        },
        {
          "name": "PIN Debit Per Item",
          "internal_name": "pin_debit_per_item",
          "amount": "0.2",
          "monthly_amount": "0.0"
        },
        {
          "name": "AMEX Per Item",
          "internal_name": "amex_per_item",
          "amount": "0.15",
          "monthly_amount": "0.0"
        },
        {
          "name": "AMEX Volume",
          "internal_name": "amex_volume",
          "amount": "0.004",
          "monthly_amount": "0.0"
        },
        {
          "name": "VMD Interchange",
          "internal_name": "vmd_interchange",
          "amount": "1.0",
          "monthly_amount": "25.03"
        },
        {
          "name": "Visa Credit NABU",
          "internal_name": "visa_credit_nabu",
          "amount": "0.0195",
          "monthly_amount": "0.06"
        },
        {
          "name": "Visa Credit Assessment",
          "internal_name": "visa_credit_assessment",
          "amount": "0.0013",
          "monthly_amount": "1.11"
        },
        {
          "name": "Visa Check NABU",
          "internal_name": "visa_check_nabu",
          "amount": "0.0155",
          "monthly_amount": "0.11"
        },
        {
          "name": "Visa Check Assessment",
          "internal_name": "visa_check_assessment",
          "amount": "0.0011",
          "monthly_amount": "1.26"
        },
        {
          "name": "Mastercard NABU",
          "internal_name": "mastercard_nabu",
          "amount": "0.0185",
          "monthly_amount": "0.0"
        },
        {
          "name": "Mastercard Assessment",
          "internal_name": "mastercard_assessment",
          "amount": "0.0012",
          "monthly_amount": "0.0"
        },
        {
          "name": "Discover NABU",
          "internal_name": "discover_nabu",
          "amount": "0.0195",
          "monthly_amount": "0.0"
        },
        {
          "name": "Discover Assessment",
          "internal_name": "discover_assessment",
          "amount": "0.0013",
          "monthly_amount": "0.0"
        },
        {
          "name": "Debit Network Access",
          "internal_name": "debit_network_access",
          "amount": "1.0",
          "monthly_amount": "0.0"
        },
        {
          "name": "AMEX OptBlue",
          "internal_name": "amex_optblue",
          "amount": "1.0",
          "monthly_amount": "0.0"
        },
        {
          "name": "PIN Debit Monthly",
          "internal_name": "pin_debit_monthly",
          "amount": "9.95",
          "monthly_amount": 0
        }
      ]
    },
    {
      "id": "8a9fa93d-574b-46ac-8a61-eddf78a8825d",
      "prospect_id": "6c77048e-28f2-4542-b807-d2b1409258b4",
      "created_at": "2019-03-26T18:32:54.195-04:00",
      "object": "proposal",
      "program_id": "06efac3f-5f48-4651-9048-1280f3dc1883",
      "merchant_activity": [
        {
          "type": "Visa",
          "volume": "19025.49",
          "transactions": "183.0"
        },
        {
          "type": "Mastercard",
          "volume": "4780.79",
          "transactions": "63.0"
        },
        {
          "type": "Discover",
          "volume": "1193.72",
          "transactions": "14.0"
        },
        {
          "type": "American Express",
          "volume": "0",
          "transactions": "0"
        },
        {
          "type": "PIN Debit",
          "volume": "0",
          "transactions": "0"
        }
      ],
      "program_features": [],
      "proposed_fees": [
        {
          "name": "VMD Volume",
          "internal_name": "vmd_volume",
          "amount": "0.0025",
          "monthly_amount": "62.5"
        },
        {
          "name": "VMD Per Item",
          "internal_name": "vmd_per_item",
          "amount": "0.08",
          "monthly_amount": "20.8"
        },
        {
          "name": "Monthly Fee",
          "internal_name": "monthly_fee",
          "amount": "9.95",
          "monthly_amount": "9.95"
        },
        {
          "name": "PCI Monthly",
          "internal_name": "pci_monthly",
          "amount": "9.95",
          "monthly_amount": "9.95"
        },
        {
          "name": "PIN Debit Per Item",
          "internal_name": "pin_debit_per_item",
          "amount": "0.2",
          "monthly_amount": "0.0"
        },
        {
          "name": "AMEX Per Item",
          "internal_name": "amex_per_item",
          "amount": "0.15",
          "monthly_amount": "0.0"
        },
        {
          "name": "AMEX Volume",
          "internal_name": "amex_volume",
          "amount": "0.004",
          "monthly_amount": "0.0"
        },
        {
          "name": "VMD Interchange",
          "internal_name": "vmd_interchange",
          "amount": "1.0",
          "monthly_amount": "345.66"
        },
        {
          "name": "Visa Credit NABU",
          "internal_name": "visa_credit_nabu",
          "amount": "0.0195",
          "monthly_amount": "1.31"
        },
        {
          "name": "Visa Credit Assessment",
          "internal_name": "visa_credit_assessment",
          "amount": "0.0013",
          "monthly_amount": "13.07"
        },
        {
          "name": "Visa Check NABU",
          "internal_name": "visa_check_nabu",
          "amount": "0.0155",
          "monthly_amount": "1.8"
        },
        {
          "name": "Visa Check Assessment",
          "internal_name": "visa_check_assessment",
          "amount": "0.0011",
          "monthly_amount": "9.87"
        },
        {
          "name": "Mastercard NABU",
          "internal_name": "mastercard_nabu",
          "amount": "0.0185",
          "monthly_amount": "1.17"
        },
        {
          "name": "Mastercard Assessment",
          "internal_name": "mastercard_assessment",
          "amount": "0.0012",
          "monthly_amount": "5.74"
        },
        {
          "name": "Discover NABU",
          "internal_name": "discover_nabu",
          "amount": "0.0195",
          "monthly_amount": "0.27"
        },
        {
          "name": "Discover Assessment",
          "internal_name": "discover_assessment",
          "amount": "0.0013",
          "monthly_amount": "1.55"
        },
        {
          "name": "Debit Network Access",
          "internal_name": "debit_network_access",
          "amount": "1.0",
          "monthly_amount": "0.0"
        },
        {
          "name": "AMEX OptBlue",
          "internal_name": "amex_optblue",
          "amount": "1.0",
          "monthly_amount": "0.0"
        },
        {
          "name": "PIN Debit Monthly",
          "internal_name": "pin_debit_monthly",
          "amount": "9.95",
          "monthly_amount": 0
        }
      ]
    }
  ]
}

This endpoint retrieves all proposals.

HTTP Request

GET https://example.com/api/v1/proposals

Query Parameters

Parameter Default Description
limit 10 Limit the number of proposals returned (valid values are integers 1 to 100).
start_after_id None Only include proposals created after user with this ID (must be UUID).

Get a Specific Proposal

curl https://example.com/api/v1/proposals/8a9fa93d-574b-46ac-8a61-eddf78a8825d \
  -H 'Authorization: 01234567890abcdef'

The above command returns JSON structured like this:

{
  "id": "8a9fa93d-574b-46ac-8a61-eddf78a8825d",
  "prospect_id": "6c77048e-28f2-4542-b807-d2b1409258b4",
  "created_at": "2019-03-26T18:32:54.195-04:00",
  "object": "proposal",
  "program_id": "06efac3f-5f48-4651-9048-1280f3dc1883",
  "merchant_activity": [
    {
      "type": "Visa",
      "volume": "19025.49",
      "transactions": "183.0"
    },
    {
      "type": "Mastercard",
      "volume": "4780.79",
      "transactions": "63.0"
    },
    {
      "type": "Discover",
      "volume": "1193.72",
      "transactions": "14.0"
    },
    {
      "type": "American Express",
      "volume": "0",
      "transactions": "0"
    },
    {
      "type": "PIN Debit",
      "volume": "0",
      "transactions": "0"
    }
  ],
  "program_features": [],
  "proposed_fees": [
    {
      "name": "VMD Volume",
      "internal_name": "vmd_volume",
      "amount": "0.0025",
      "monthly_amount": "62.5"
    },
    {
      "name": "VMD Per Item",
      "internal_name": "vmd_per_item",
      "amount": "0.08",
      "monthly_amount": "20.8"
    },
    {
      "name": "Monthly Fee",
      "internal_name": "monthly_fee",
      "amount": "9.95",
      "monthly_amount": "9.95"
    },
    {
      "name": "PCI Monthly",
      "internal_name": "pci_monthly",
      "amount": "9.95",
      "monthly_amount": "9.95"
    },
    {
      "name": "PIN Debit Per Item",
      "internal_name": "pin_debit_per_item",
      "amount": "0.2",
      "monthly_amount": "0.0"
    },
    {
      "name": "AMEX Per Item",
      "internal_name": "amex_per_item",
      "amount": "0.15",
      "monthly_amount": "0.0"
    },
    {
      "name": "AMEX Volume",
      "internal_name": "amex_volume",
      "amount": "0.004",
      "monthly_amount": "0.0"
    },
    {
      "name": "VMD Interchange",
      "internal_name": "vmd_interchange",
      "amount": "1.0",
      "monthly_amount": "345.66"
    },
    {
      "name": "Visa Credit NABU",
      "internal_name": "visa_credit_nabu",
      "amount": "0.0195",
      "monthly_amount": "1.31"
    },
    {
      "name": "Visa Credit Assessment",
      "internal_name": "visa_credit_assessment",
      "amount": "0.0013",
      "monthly_amount": "13.07"
    },
    {
      "name": "Visa Check NABU",
      "internal_name": "visa_check_nabu",
      "amount": "0.0155",
      "monthly_amount": "1.8"
    },
    {
      "name": "Visa Check Assessment",
      "internal_name": "visa_check_assessment",
      "amount": "0.0011",
      "monthly_amount": "9.87"
    },
    {
      "name": "Mastercard NABU",
      "internal_name": "mastercard_nabu",
      "amount": "0.0185",
      "monthly_amount": "1.17"
    },
    {
      "name": "Mastercard Assessment",
      "internal_name": "mastercard_assessment",
      "amount": "0.0012",
      "monthly_amount": "5.74"
    },
    {
      "name": "Discover NABU",
      "internal_name": "discover_nabu",
      "amount": "0.0195",
      "monthly_amount": "0.27"
    },
    {
      "name": "Discover Assessment",
      "internal_name": "discover_assessment",
      "amount": "0.0013",
      "monthly_amount": "1.55"
    },
    {
      "name": "Debit Network Access",
      "internal_name": "debit_network_access",
      "amount": "1.0",
      "monthly_amount": "0.0"
    },
    {
      "name": "AMEX OptBlue",
      "internal_name": "amex_optblue",
      "amount": "1.0",
      "monthly_amount": "0.0"
    },
    {
      "name": "PIN Debit Monthly",
      "internal_name": "pin_debit_monthly",
      "amount": "9.95",
      "monthly_amount": 0
    }
  ]
}

This endpoint retrieves a specific proposal.

HTTP Request

GET https://example.com/api/v1/proposals/{id}

URL Parameters

Parameter Description
id The ID of the proposal to retrieve

Create a Simple Proposal

curl https://example.com/api/v1/proposals/simple \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"prospect_id": "9136dff2-bc86-4f71-8f0e-84dbb33a4ed0", "total_volume": "20000", "avg_ticket": "37.90"}'

The above command returns JSON structured like this:

{
  "id": "33ebe2d9-a717-4507-9933-fbc455748c69",
  "prospect_id": "9136dff2-bc86-4f71-8f0e-84dbb33a4ed0",
  "created_at": "2019-03-28T11:18:10.822-04:00",
  "object": "proposal",
  "program_id": "06efac3f-5f48-4651-9048-1280f3dc1883",
  "merchant_activity": [
    {
      "type": "Visa",
      "volume": "14959.34",
      "transactions": "401.0"
    },
    {
      "type": "Mastercard",
      "volume": "4932.77",
      "transactions": "122.0"
    },
    {
      "type": "Discover",
      "volume": "107.89",
      "transactions": "4.0"
    },
    {
      "type": "American Express",
      "volume": "0",
      "transactions": "0"
    },
    {
      "type": "PIN Debit",
      "volume": "0",
      "transactions": "0"
    }
  ],
  "program_features": [],
  "proposed_fees": [
    {
      "name": "AMEX OptBlue",
      "internal_name": "amex_optblue",
      "amount": "1.0",
      "monthly_amount": "0.0"
    },
    {
      "name": "AMEX Per Item",
      "internal_name": "amex_per_item",
      "amount": "0.15",
      "monthly_amount": "0.0"
    },
    {
      "name": "AMEX Volume",
      "internal_name": "amex_volume",
      "amount": "0.004",
      "monthly_amount": "0.0"
    },
    {
      "name": "Debit Network Access",
      "internal_name": "debit_network_access",
      "amount": "1.0",
      "monthly_amount": "0.0"
    },
    {
      "name": "Discover Assessment",
      "internal_name": "discover_assessment",
      "amount": "0.0013",
      "monthly_amount": "0.14"
    },
    {
      "name": "Discover NABU",
      "internal_name": "discover_nabu",
      "amount": "0.0195",
      "monthly_amount": "0.08"
    },
    {
      "name": "Mastercard Assessment",
      "internal_name": "mastercard_assessment",
      "amount": "0.0012",
      "monthly_amount": "5.92"
    },
    {
      "name": "Mastercard NABU",
      "internal_name": "mastercard_nabu",
      "amount": "0.0185",
      "monthly_amount": "2.26"
    },
    {
      "name": "Monthly Fee",
      "internal_name": "monthly_fee",
      "amount": "9.95",
      "monthly_amount": "9.95"
    },
    {
      "name": "PCI Monthly",
      "internal_name": "pci_monthly",
      "amount": "9.95",
      "monthly_amount": "9.95"
    },
    {
      "name": "PIN Debit Monthly",
      "internal_name": "pin_debit_monthly",
      "amount": "9.95",
      "monthly_amount": 0
    },
    {
      "name": "PIN Debit Per Item",
      "internal_name": "pin_debit_per_item",
      "amount": "0.2",
      "monthly_amount": "0.0"
    },
    {
      "name": "Visa Check Assessment",
      "internal_name": "visa_check_assessment",
      "amount": "0.0011",
      "monthly_amount": "12.63"
    },
    {
      "name": "Visa Check NABU",
      "internal_name": "visa_check_nabu",
      "amount": "0.0155",
      "monthly_amount": "4.85"
    },
    {
      "name": "Visa Credit Assessment",
      "internal_name": "visa_credit_assessment",
      "amount": "0.0013",
      "monthly_amount": "4.52"
    },
    {
      "name": "Visa Credit NABU",
      "internal_name": "visa_credit_nabu",
      "amount": "0.0195",
      "monthly_amount": "1.72"
    },
    {
      "name": "VMD Interchange",
      "internal_name": "vmd_interchange",
      "amount": "1.0",
      "monthly_amount": "252.22"
    },
    {
      "name": "VMD Per Item",
      "internal_name": "vmd_per_item",
      "amount": "0.08",
      "monthly_amount": "42.16"
    },
    {
      "name": "VMD Volume",
      "internal_name": "vmd_volume",
      "amount": "0.0025",
      "monthly_amount": "50.0"
    }
  ]
}

This endpoint creates a simple proposal. This corresponds to the standard / simple form in the quote tool.

HTTP Request

POST https://example.com/api/v1/proposals/simple

Attributes

Attribute Type Description
avg_ticket numeric string Average VMD transaction amount in dollars
num_transactions numeric string Number of VMD transactions
preferred_program_id uuid ID of program to propose if possible
prospect_id uuid ID of prospect to create proposal for
total_fees numeric string The total fees being paid now in dollars
total_volume numeric string Total VMD volume in dollars

prospect_id and total_volume are required along with avg_ticket or num_transactions.

Prospects

Prospect Definition

Attribute Type Description
business_name string Name of business
contact_name string Name of contact at business
created_at timestamp When the user was created formatted in ISO8601
email email Email address
id uuid Unique identifier
mcc string Merchant category code
phone string Phone number
prospect_stage_id uuid Prospect Stage ID
source_type string Source of prospect
user_id uuid User ID that owns prospect

Get All Prospects

curl "https://example.com/api/v1/prospects" \
  -H "Authorization: 01234567890abcdef"

The above command returns JSON structured like this:

{
  "object": "list",
  "data": [
    {
      "id": "0e68f57d-e361-4ea1-a827-0ce6256adf77",
      "business_name": "Sal's Subs",
      "contact_name": "Sal",
      "phone": "555-5555",
      "email": "sal@example.com",
      "source_type": "in-person",
      "user_id": "c742ce38-daa2-4011-a9b1-c85459186436",
      "merchant_type_id": "9cd01d9c-4994-48b1-8246-9ecde769ae7c",
      "prospect_stage_id": "7365ec0e-0aab-406c-b54e-3c6ed9f483d3",
      "created_at": "2019-03-25T16:30:45.941-04:00",
      "object": "prospect"
    },
    {
      "id": "ab593f14-f2de-4ae0-a260-d1ac28d4badf",
      "business_name": "Acme Food Stuffs",
      "contact_name": "Phil",
      "phone": "555-5555",
      "email": "phil@example.com",
      "source_type": "web",
      "user_id": "c742ce38-daa2-4011-a9b1-c85459186436",
      "merchant_type_id": "7447c292-332b-4c36-86a1-aa5ba256a4e8",
      "prospect_stage_id": "1ae64c8a-66be-42f9-902c-5dc92bb70f3b",
      "created_at": "2019-03-25T16:26:54.944-04:00",
      "object": "prospect"
    }
  ]
}

This endpoint retrieves all prospects sorted by created_at ascending.

HTTP Request

GET https://example.com/api/v1/prospects

Query Parameters

Parameter Default Description
limit 10 Limit the number of prospects returned (valid values are integers 1 to 100).
start_after_id None Only include prospects created after user with this ID (must be UUID).

Get a Specific Prospect

curl https://example.com/api/v1/prospects/ab593f14-f2de-4ae0-a260-d1ac28d4badf \
  -H 'Authorization: 01234567890abcdef'

The above command returns JSON structured like this:

  {
    "id": "ab593f14-f2de-4ae0-a260-d1ac28d4badf",
    "business_name": "Acme Food Stuffs",
    "contact_name": "Phil",
    "phone": "555-5555",
    "email": "phil@example.com",
    "source_type": "web",
    "user_id": "c742ce38-daa2-4011-a9b1-c85459186436",
    "merchant_type_id": "7447c292-332b-4c36-86a1-aa5ba256a4e8",
    "prospect_stage_id": "1ae64c8a-66be-42f9-902c-5dc92bb70f3b",
    "created_at": "2019-03-25T16:26:54.944-04:00",
    "object": "prospect"
  }

This endpoint retrieves a specific prospect.

HTTP Request

GET https://example.com/api/v1/prospect/{id}

URL Parameters

Parameter Description
id The ID of the prospect to retrieve

Create a Prospect

curl https://example.com/api/v1/prospects \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"user_id": "c742ce38-daa2-4011-a9b1-c85459186436", "merchant_type_id": "196a094a-16a4-4fda-8007-9300ef9c5cf8", "prospect_stage_id": "1ae64c8a-66be-42f9-902c-5dc92bb70f3b", "business_name": "Fancy Burgers", "contact_name": "Sam", "phone": "555-5555", "email": "sam@example.com", "source_type": "search engine"}'

The above command returns JSON structured like this:

{
  "id": "73458508-0ef5-4abb-9715-ceed559583f6",
  "business_name": "Fancy Burgers",
  "contact_name": "Sam",
  "phone": "555-5555",
  "email": "sam@example.com",
  "source_type": "search engine",
  "user_id": "c742ce38-daa2-4011-a9b1-c85459186436",
  "merchant_type_id": "196a094a-16a4-4fda-8007-9300ef9c5cf8",
  "prospect_stage_id": "1ae64c8a-66be-42f9-902c-5dc92bb70f3b",
  "created_at": "2019-03-25T16:48:21.543-04:00",
  "object": "prospect"
}

This endpoint creates a prospect.

HTTP Request

POST https://example.com/api/v1/users

Required Attributes

Attribute Type Description
prospect_stage_id uuid Prospect Stage ID
source_type string Source of prospect
user_id uuid User ID that owns prospect

Allowed Attributes

Attribute Type Default Description
business_name string None Name of business
contact_name string None Name of contact at business
mcc string None Merchant category code
email email None Email address
phone string None Phone number

Update a Specific Prospect

curl https://example.com/api/v1/prospects/73458508-0ef5-4abb-9715-ceed559583f6 \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"email": "john@example.com"}'

The above command returns JSON structured like this:

{
  "id": "73458508-0ef5-4abb-9715-ceed559583f6",
  "business_name": "Fancy Burgers",
  "contact_name": "Sam",
  "phone": "555-5555",
  "email": "john@example.com",
  "source_type": "search engine",
  "user_id": "c742ce38-daa2-4011-a9b1-c85459186436",
  "merchant_type_id": "196a094a-16a4-4fda-8007-9300ef9c5cf8",
  "prospect_stage_id": "1ae64c8a-66be-42f9-902c-5dc92bb70f3b",
  "created_at": "2019-03-25T16:48:21.543-04:00",
  "object": "prospect"
}

This endpoint updates a prospect.

HTTP Request

PATCH https://example.com/api/v1/prospects/{id}

URL Parameters

Parameter Description
id The ID of the prospect to update

Allowed Attributes

Attribute Type Description
business_name string Name of business
contact_name string Name of contact at business
email email Email address
mcc string None
phone string Phone number
prospect_stage_id uuid Prospect Stage ID
source_type string Source of prospect
user_id uuid User ID that owns prospect

Delete a Specific Prospect

curl https://example.com/api/v1/prospects/73458508-0ef5-4abb-9715-ceed559583f6 \
  -H 'Authorization: 01234567890abcdef' \
  -X DELETE

The above command does not return a response body.

This endpoint deletes a specific prospect.

HTTP Request

DELETE https://example.com/api/v1/prospects/{id}

URL Parameters

Parameter Description
id The ID of the prospect to delete

Prospect Stages

Prospect Stage Definition

Attribute Type Description
id uuid Unique identifier
name string Name

Get All Prospect Stages

curl "https://example.com/api/prospect_stages" \
  -H "Authorization: 01234567890abcdef"

The above command returns JSON structured like this:

{
  "object": "list",
  "data": [
    {
      "id": "1ae64c8a-66be-42f9-902c-5dc92bb70f3b",
      "name": "Prospect",
      "object": "prospect_stage"
    },
    {
      "id": "2bb0ca43-b47a-408d-a48c-322ad3453905",
      "name": "Quoted",
      "object": "prospect_stage"
    },
    {
      "id": "6820bc00-2aaa-472f-bda7-eeb64c9c5dbd",
      "name": "Closed-Yes",
      "object": "prospect_stage"
    },
    {
      "id": "7365ec0e-0aab-406c-b54e-3c6ed9f483d3",
      "name": "Contacted",
      "object": "prospect_stage"
    },
    {
      "id": "944e129f-635c-4a16-b9cd-0d6965b2b1fa",
      "name": "Closed-No",
      "object": "prospect_stage"
    }
  ]
}

This endpoint retrieves all merchant types.

HTTP Request

GET https://example.com/api/prospect_stages

Get a Specific Prospect Stage

curl https://example.com/api/prospect_stages/944e129f-635c-4a16-b9cd-0d6965b2b1fa \
  -H 'Authorization: 01234567890abcdef'

The above command returns JSON structured like this:

{
  "id": "944e129f-635c-4a16-b9cd-0d6965b2b1fa",
  "name": "Closed-No",
  "object": "prospect_stage"
}

This endpoint retrieves a specific prospect stage.

HTTP Request

GET https://example.com/api/prospect_stages/{id}

URL Parameters

Parameter Description
id The ID of the prospect stage to retrieve

Users

User Definition

Attribute Type Description
admin bool Is user an administrator
creationTime integer Unix time (i.e. number of seconds since 1970-01-01 00:00:00 UTC)
email email Email address
id uuid Unique identifier
name string Name
userName string User name (may be used for vanity quote URL)

In addition, a user's password may be assigned on creation or reset later via the API. The password is securely digested and cannot be read via the API. However, it is preferable to use single sign-on rather than managing passwords via the API.

Get All Users

curl "https://example.com/api/users" \
  -H "Authorization: 01234567890abcdef"

The above command returns JSON structured like this:

{
  "object": "list",
  "data": [
    {
      "id": "086fa4f9-1c54-47c5-8cc7-df4ac8b52f81",
      "email": "john@example.com",
      "userName": "john",
      "name": "John Doe",
      "admin": false,
      "object": "user",
      "creationTime": 1587745044
    },
    {
      "id": "446f6f42-6ed7-4957-b922-8f60e37e65d1",
      "email": "jane@example.com",
      "userName": "jane",
      "name": "Jane Doe",
      "admin": false,
      "object": "user",
      "creationTime": 1573666167
    },
  ]
}

This endpoint retrieves all users sorted by creationTime ascending.

HTTP Request

GET https://example.com/api/users

Query Parameters

Parameter Default Description
limit 10 Limit the number of users returned (valid values are integers 1 to 100).
startAfterId None Only include users created after user with this ID (must be UUID).

Get a Specific User

curl https://example.com/api/users/446f6f42-6ed7-4957-b922-8f60e37e65d1 \
  -H 'Authorization: 01234567890abcdef'

The above command returns JSON structured like this:

{
  "id": "446f6f42-6ed7-4957-b922-8f60e37e65d1",
  "email": "jane@example.com",
  "userName": "jane",
  "name": "Jane Doe",
  "admin": false,
  "object": "user",
  "creationTime": 1587745044
}

This endpoint retrieves a specific user.

HTTP Request

GET https://example.com/api/users/{id}

URL Parameters

Parameter Description
id The ID of the user to retrieve

Create a User

curl https://example.com/api/users \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"email": "john@example.com", "userName": "john", "name": "John Smith", "admin": "false"}'

The above command returns JSON structured like this:

{
  "id": "446f6f42-6ed7-4957-b922-8f60e37e65d1",
  "email": "john@example.com",
  "userName": "john",
  "name": "John Smith",
  "admin": false,
  "object": "user",
  "creationTime": 1587745044
}

This endpoint creates a user. As an alternative, single sign-on can be configured to create users on first sign-on.

HTTP Request

POST https://example.com/api/users

Required Attributes

Attribute Type Description
email email Email address
name string Name
userName string User name (must match this regexp: /\A[a-z][a-z0-9-]*\z/)

Allowed Attributes

Attribute Type Default Description
admin bool false Is user an administrator
password string Unguessable random string Login password

Update a Specific User

curl https://example.com/api/users/446f6f42-6ed7-4957-b922-8f60e37e65d1 \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"email": "john@example.com", "userName": "john", "name": "John Smith", "admin": "false"}'

The above command returns JSON structured like this:

{
  "id": "446f6f42-6ed7-4957-b922-8f60e37e65d1",
  "email": "john@example.com",
  "userName": "john",
  "name": "John Smith",
  "admin": false,
  "object": "user",
  "creationTime": 1587745044
}

This endpoint updates a user.

HTTP Request

PATCH https://example.com/api/users/{id}

URL Parameters

Parameter Description
id The ID of the user to update

Allowed Attributes

Attribute Type Description
admin bool Is user an administrator
email email Email address
name string Name
password string Login password
userName string User name (must match this regexp: /\A[a-z][a-z0-9-]*\z/)

Delete a Specific User

curl https://example.com/api/users/446f6f42-6ed7-4957-b922-8f60e37e65d1 \
  -H 'Authorization: 01234567890abcdef' \
  -X DELETE

The above command does not return a response body.

This endpoint deletes a specific user.

HTTP Request

DELETE https://example.com/api/users/{id}

URL Parameters

Parameter Description
id The ID of the user to delete

Events

Event are created when something of note happens such as a statement analysis being completed. They can be pulled from the events API or pushed via webhook.

Event Definition

Attribute Type Description
data object Event data - see below for possible formats
id uuid Unique identifier
time integer Unix time (i.e. number of seconds since 1970-01-01 00:00:00 UTC)
type string Event type - see below for possible values

analysis.requested

A statement analysis was requested.

Attribute Type Description
statementAnalysisId uuid ID of the statement analysis
agentId integer ID of the requesting agent
name string Name of the statement analysis

analysis.completed

A statement analysis was completed.

Attribute Type Description
statementAnalysisId uuid ID of the statement analysis
proposalId uuid ID of the created proposal

analysis.rejected

A statement analysis was completed.

Attribute Type Description
statementAnalysisId uuid ID of the statement analysis

Get All Events

curl "https://example.com/api/events" \
  -H "Authorization: 01234567890abcdef"

The above command returns JSON structured like this:

{
  "object": "list",
  "hasMore": false,
  "data": [
    {
      "id": "680adba7-d2a8-4df7-82b4-01ae0411827f",
      "object": "event",
      "time": 1650297407,
      "type": "statement_analysis.requested",
      "data": {
        "statementAnalysisId": "477966ab-69b7-4253-a1c6-dd8700de6bd5",
        "agentId": 12345,
        "name": "Acme March 2022"
      }
    },
    {
      "id": "1ac3b8ad-726d-4a0c-9821-88dd409e8487",
      "object": "event",
      "time": 1650297962,
      "type": "statement_analysis.completed",
      "data": {
        "statementAnalysisId": "477966ab-69b7-4253-a1c6-dd8700de6bd5",
        "proposalId": "059036f7-2f35-43c5-b968-46dc082ecf33"
      }
    },
    {
      "id": "46cf64a1-a493-4236-a108-5a18884d10aa",
      "object": "event",
      "time": 1650299106,
      "type": "statement_analysis.requested",
      "data": {
        "statementAnalysisId": "8a4e5959-0ff5-4b67-9441-e131ba6f1514",
        "agentId": 23456,
        "name": "Mar 22 Merchant Statement.pdf"
      }
    },
    {
      "id": "9bbaff5b-0177-4521-a3f1-96db1e28eab5",
      "object": "event",
      "time": 1650301580,
      "type": "statement_analysis.completed",
      "data": {
        "statementAnalysisId": "8a4e5959-0ff5-4b67-9441-e131ba6f1514",
        "proposalId": "326a4ced-9790-4e28-8a67-fc8f986f0948"
      }
    },
  ]
}

This endpoint retrieves all events. If hasMore is true then more events are available which can be fetched using the startAfterId query parameter.

HTTP Request

GET https://example.com/api/events

Query Parameters

Parameter Default Description
limit 25 Limit the number of events returned (valid values are integers 1 to 100).
startTime None Only include events created at this time or later (must be integer number of seconds since Unix epoch).
startAfterId None Only include events after event with this ID (must be UUID). Can be used for pagination.

Get a Specific Event

curl https://example.com/api/events/602a7d68-f732-447f-86d6-65005152dde1 \
  -H 'Authorization: 01234567890abcdef'

The above command returns JSON structured like this:

{
  "id": "602a7d68-f732-447f-86d6-65005152dde1",
  "object": "event",
  "time": 1650301630,
  "type": "statement_analysis.completed",
  "data": {
    "statementAnalysisId": "477966ab-69b7-4253-a1c6-dd8a00de6bd5",
    "proposalId": "f841cda7-d34f-48c3-b803-412ca4179736"
  }
}

This endpoint retrieves a specific event.

HTTP Request

GET https://example.com/api/events/{id}

URL Parameters

Parameter Description
id The ID of the event to retrieve

Webhooks

Webhooks are a way of being notified when an event occurs.

Get All Webhooks

curl "https://example.com/api/webhooks" \
  -H "Authorization: 01234567890abcdef"

The above command returns JSON structured like this:

{
  "object": "list",
  "data": [
    {
      "id": 1234,
      "object": "webhook",
      "url": "https://example.com/requested",
      "eventTypes": [
        "statement_analysis.requested"
      ],
      "hmacSecret": "11f2baa04e4642de3b5c3d66ada815bc2d8a8515e00b08285d159a8d72993bfc"
    },
    {
      "id": 56789,
      "object": "webhook",
      "url": "https://example.com/finished",
      "eventTypes": [
        "statement_analysis.completed",
        "statement_analysis.rejected"
      ],
      "hmacSecret": "a91e971e50388871a355b55423a909786381f2628353fba939c4ba19302d3734"
    }
  ]
}

This endpoint retrieves all webhooks.

HTTP Request

GET https://example.com/api/webhooks

Get a Specific Webhook

curl "https://example.com/api/webhooks/1234" \
  -H "Authorization: 01234567890abcdef"

The above command returns JSON structured like this:

{
  "id": 1234,
  "object": "webhook",
  "url": "https://example.com/requested",
  "eventTypes": [
    "statement_analysis.requested"
  ],
  "hmacSecret": "11f2baa04e4642de3b5c3d66ada815bc2d8a8515e00b08285d159a8d72993bfc"
}

This endpoint retrieves a specific webhook.

HTTP Request

GET https://example.com/api/webhooks/{id}

URL Parameters

Parameter Description
id The ID of the webhook to retrieve

Create a Webhook

curl https://example.com/api/webhooks \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"url": "https://example.com/webhook", "eventTypes": ["statement_analysis.completed", "statement_analysis.rejected"]}'

The above command returns JSON structured like this:

{
  "id": 1234,
  "hmacSecret": "4eb417493e09ac36ee2d998b6fb4306f1d428ae4577f30d521cd703f598f117b"
}

This endpoint creates a webhook.

HTTP Request

POST https://example.com/api/webhooks

Required Attributes

Attribute Type Description
url string URL to send webhook requests
eventTypes array Only events of these types that will be delivered

Update a Webhook

curl https://example.com/api/webhooks/1234 \
  -H 'Authorization: 01234567890abcdef' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"url": "https://example.com/webhook", "eventTypes": ["statement_analysis.completed", "statement_analysis.rejected"]}'

The above command returns an HTTP 200 without a body.

This endpoint updates a webhook.

HTTP Request

PATCH https://example.com/api/webhooks/{id}

Required Attributes

Attribute Type Description
id integer ID of webhook to update
url string URL to send webhook requests
eventTypes array Only events of these types that will be delivered

Delete a Webhook

curl https://example.com/api/webhooks/1234 \
  -H 'Authorization: 01234567890abcdef' \
  -X DELETE

The above command returns an HTTP 200 without a body.

This endpoint deletes a webhook.

HTTP Request

DELETE https://example.com/api/webhooks/{id}

Required Attributes

Attribute Type Description
id integer ID of webhook to update

Request Signatures

Webhook requests include a Isoamp-Signature header that is the signature of the request. The signature consists of multiple key=value pairs separated by commas. The value of the pair with the key t is the time the request was sent in Unix time. The value of the pair with the key v1 is an HMAC of t and the request body keyed by the webhook hmacSecret.

To validate a signature concatenate t with the request body. Compute an HMAC of this with key hmacSecret and the SHA-256 algorithm. For example this could be done with the following code in Ruby.

require 'openssl' # => true

# isoamp_signature is the value of the "Isoamp-Signature" header.
isoamp_signature = "t=1650654842,v1=143f3835f2bf090fa6fd78754517d51b1897f691682627d241c5ed309cad0515"

# body is complete request body.
body = '{"id":"f9a6e449-e884-4726-973e-26d6bd99666a","object":"event","time":1650654842,"type":"statement_analysis.completed","data":{"statementAnalysisId":"f472949d-8227-4514-aa1c-b40f1f00380c","proposalId":"f9a4bb9c-d
2b2-45fa-83fe-f895c74235ad"}}'

# hmac_secret is a unique attribute for each webhook.
hmac_secret = "f76fab345ce93a69aa77d68a08283400cd0b45cb0a0a16b61e20b4c1e626a115"

# Parse the signature.
sig_parts = isoamp_signature.split(",").map { |pair| pair.split("=") }.to_h
# => {"t"=>"1650654842", "v1"=>"143f3835f2bf090fa6fd78754517d51b1897f691682627d241c5ed309cad0515"}

expected_sig = OpenSSL::HMAC.hexdigest("SHA256", hmac_secret, "#{sig_parts["t"]}#{body}")
# => "143f3835f2bf090fa6fd78754517d51b1897f691682627d241c5ed309cad0515"

# Test v1 that matches the expected signature.
expected_sig == sig_parts["v1"] #=> true

# Test that the request was sent recently to prevent replay.
Time.at(sig_parts["t"].to_i) #=> 2022-04-22 14:14:02 -0500