NAV Navbar
shell go

Introduction

The AdvicePay API is organized around REST. Our API has predictable resource-oriented URLs, accepts and returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

You can use the API through our test environment, which does not affect your live data or interact with banking networks.

For testing, the base URL is https://demo.advicepay.com. For live requests, https://app.advicepay.com is the base URL.

Authentication

curl "api_endpoint_here"
  -H "Authorization: Bearer advicepay_api_token_or_access_token_here"
import "net/http"

req, _ := http.NewRequest("GET", "api_endpoint_here", nil)
req.Header.Add("Authorization", "Bearer advicepay_api_token_or_access_token")
resp, _ := http.DefaultClient.Do(req)

The AdvicePay uses private API keys to allow access to the API. AdvicePay expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer advicepay_api_token_or_access_token

There are 2 methods of authentication available: API token and Oauth.

API Token

This method is useful for a firm-level integration where all AdvicePay users are under the same account. API tokens are securely provisioned upon request and can be recycled upon request as well.

For API calls, place the API token in the Authorization header.

Authorization: Bearer api_token_here

Oauth

This method is useful for a user-level integration where AdvicePay users might be under different accounts. Oauth clients are added upon request. You will need to provide your company name, website URL, logo, and redirect URI. A client ID and secret will be securely provisioned. AdvicePay currently offers a standard Oauth 2.0 Authorization Code grant type. The flow to authorize users for your app is:

  1. Users are redirected to AdvicePay by your site and prompted to authorize your app
  2. Users are redirected back to your site by AdvicePay
  3. Your site requests an access token using an authorization code

1. Requesting authorization from the user

HTTP Request

GET /oauth2/authorize

Query Parameters

Parameter Description
client_id Your provisioned client ID
redirect_uri The URL in your application where users will be sent after authorization (must match what is provided when initially getting your Oauth client provisioned)
scope Currently, only all is supported
state (optional) An arbitrary string used to protect against cross-site request forgery attacks

2. Users are redirected back to your site by AdvicePay

If the user accepts your request, AdvicePay redirects back to your site with a temporary code as a query parameter as well as the state you provided in the previous step. The temporary code will expire after 10 minutes. If the states don't match, then a third party created the request, and you should abort the process.

For example, if your redirect URI is http://localhost/example and you provided the state xj15na in the previous step, your application would receive a GET request at the following URL upon upon authorization:

http://localhost/example?code=3fbbcd39-cd9c&state=xj15na

If the user rejects access, your application would receive a GET request at the following URL:

http://localhost/example?error=access_denied&state=xj15na

3. Requesting an access token

HTTP Request

POST /oauth2/access_token

Form Fields

Parameter Description
client_id Your provisioned client ID
client_secret Your provisioned client secret
code The authorization code you received at the redirect URI in the previous step
redirect_uri The URL in your application where users will be sent after authorization. It is used here to verify your Oauth client credentials.
state (optional) The arbitrary string you provided in step 1

You will get a JSON response containing an access token for the user. This access token should be stored securely and not be exposed outside of making API calls to AdvicePay.

{"access_token": "228c9f52-c003", "scope": scope, "token_type": "bearer"}

For API calls, place the access token in the Authorization header.

Authorization: Bearer 228c9f52-c003

The /me endpoint

This endpoint returns information about the user your API call is authorizing as.

Example Request

curl /api/public/v1/me \
     -H "Authorization: Bearer advicepay_api_key"
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/me", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "parentID":32,
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "parentRoleTitle":"Firm Manager",
  "accountOwner":false,
}

HTTP Request

GET /api/public/v1/me

Response

Value Type Description
id number This is the user's unique indentifier, and should be stored to do any future queries for data belonging to that user.
createdAt number This is the unix timestamp for when the user was created.
updatedAt number This is the unix timestamp for when the user was updated.
deletedAt number This is the unix timestamp for when the user was deleted.
email string The user's email address.
parentID number If the user is an Admin/Analyst, this is the ID of the user that this record is nested under.
parentRoleTitle string If the user is an Admin/Analyst, this is the Role of the user that this record is nested under.
externalID string This is used to specify an identifier from your system in the AdvicePay database.
firstName string User's first name.
lastName string User's last name.
verified boolean This reflects whether or not the user has verified their email and set a password.
roleTitle string This describes the user's specific role, and the implied abilities that go with that.
accountOwner boolean This describes whether the user is the owner of the account they are in.

Offices

Offices are only applicable to Enterprise accounts. Essential and Professional accounts have no concept of multiple Offices.

The Office Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "name":"Example Office"
}

Attributes

Value Type Description
id number This is the office's unique indentifier, and should be stored to do any future queries for data belonging to that office.
createdAt number This is the unix timestamp for when the office was created.
updatedAt number This is the unix timestamp for when the office was updated.
deletedAt number This is the unix timestamp for when the office was deleted.
name string The name of the office.

Get an Office

Example Request

curl /api/public/v1/offices/1 \
     -H "Authorization: Bearer advicepay_api_key"
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/offices/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "name":"Example Office",
}

Required Permissions

User must be the Account Owner or an Admin/Analyst under the Account Owner.

HTTP Request

GET /api/public/v1/offices/<ID>

URL Parameters

Parameter Description
ID The ID of the office to fetch.

Response

Returns the requested office

Create an Office

Example Request

curl /api/public/v1/offices \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"name":"Example Office"}' \
     -X POST
import "net/http"

type createOfficeReq struct {
    Name string `json:"name"`
}

// Marshall request data to JSON string
data := createOfficeReq{
  Name: "Example Office",
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/offices", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "name":"Example Office",
}

Required Permissions

User must be the Account Owner or an Admin under the Account Owner.

HTTP Request

POST /api/public/v1/offices

Arguments

Value Required Type Description
name true string The name of the office. Trailing or leading whitespace will be trimmed.

Response

The newly created Office object, if the call succeeded. If the request failed, this call returns an error.

Update an Office

Example Request

curl /api/public/v1/offices/1 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"name":"Updated Example Office"}' \
     -X PUT
import "net/http"

type updateOfficeReq struct {
    Name string `json:"name"`
}

// Marshall request data to JSON string
data := updateOfficeReq{
  Name: "Updated Example Office",
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("PUT", "/api/public/v1/offices/1", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "name":"Updated Example Office",
}

Required Permissions

User must be the Account Owner or an Admin under the Account Owner.

HTTP Request

PUT /api/public/v1/offices/<ID>

Arguments

Value Required Type Description
name true string The new name of the office. Trailing or leading whitespace will be trimmed.

Response

The updated Office object, if the call succeeded. If the request failed, this call returns an error.

List Offices

Example Request

curl /api/public/v1/offices \
     -H "Authorization: Bearer advicepay_api_key" \
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/offices", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":null,
      "name":"Example Office",
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

Required Permissions

User must be the Account Owner or an Admin/Analyst under the Account Owner.

HTTP Request

GET /api/public/v1/offices

Query Parameters

Parameter Default Type Description
page 1 number This will determine which page to return.
perPage 10 number This will determine the number of records to return (max is 100).

Response

Returns a list of offices sorted by created_at in descending order

Admins

Admins are only applicable to Professional and Enterprise accounts. Essential accounts do not support the admin user feature.

The Admin Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "parentID":1,
  "roleTitle":"Admin"
}

Attributes

Value Type Description
id number This is the admin's unique indentifier.
createdAt number This is the unix timestamp for when the admin was created.
updatedAt number This is the unix timestamp for when the admin was updated.
deletedAt number This is the unix timestamp for when the admin was deleted.
email string This is validated for uniqueness.
firstName string Admin's first name.
lastName string Admin's last name.
parentID number This is the unique ID of the advisor whose account the admin is associated with.
roleTitle string This describes the admin's specific role, and the implied abilities that go with that.

Create an Admin

Example Request

curl /api/public/v1/admins \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "parentID":1, "disableDirectLogin":false, "permission":"Admin"}' \
     -X POST
import "net/http"

type createAdminReq struct {
    ParentID           uint   `json:"parentID"`
    Email              string `json:"email"`
    FirstName          string `json:"firstName"`
    LastName           string `json:"lastName"`
    Permission         string `json:"permission"`
    DisableDirectLogin bool   `json:"disableDirectLogin"`
    SSOSource          string `json:"ssoSource"`
    SSOID              string `json:"ssoID"`
}

// Marshall request data to JSON string
data := createAdminReq{
  ParentID:           1,
  Email:              "example@advicepay.com",
  FirstName:          "first",
  LastName:           "last",
  Permission:         "Admin",
  DisableDirectLogin: false,
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/admins", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "parentID":1,
  "roleTitle":"Admin",
}

Required Permissions

User must be Managing Advisor or an Admin under a Managing Advisor.

HTTP Request

POST /api/public/v1/admins

Arguments

Value Required Type Description
email true string Email is validated for correct format and then for uniqueness in our database.
firstName true string Trailing or leading whitespaces will be trimmed.
lastName true string Trailing or leading whitespaces will be trimmed.
permission true string Must be one of the following: "Admin", "Analyst". "Admin" gives the same access and functionality as the parent user. "Analyst" gives read-only access to the parent user's account.
parentID true number The unique ID of the advisor whose account the admin will associated with. "Admin" and "Analyst" may be associated with the account owner (permission "Managing Advisor") or a standard advisor (permission "Advisor"). "Read-only Advisor" accounts may only be associated with an "Analyst".
disableDirectLogin false boolean If set to true, the admin will only be able to login using SSO.
ssoSource conditional string If disableDirectLogin is set to true, this field is required to enable SSO login. The source is usually your company name.
ssoID conditional string If disableDirectLogin is set to true, this field is required to enable SSO login. The ID will be your unique idenitifier to create the SSO link between AdvicePay and your platform. Note that ssoID is not visible in the application UI.

Response

The newly created Admin object, if the call succeeded. If the request failed, this call returns an error.

Advisors

Advisors are only applicable to Professional and Enterprise accounts. Essential accounts are single user and have no concept of multiple Advisors.

The Advisor Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1
}

Attributes

Value Type Description
id number This is the advisor's unique indentifier, and should be stored to do any future queries for data belonging to that advisor.
createdAt number This is the unix timestamp for when the advisor was created.
updatedAt number This is the unix timestamp for when the advisor was updated.
deletedAt number This is the unix timestamp for when the advisor was deleted.
email string This is validated for uniqueness.
externalID string This is used to specify an identifier from your system in the AdvicePay database.
firstName string Advisor's first name.
lastName string Advisor's last name.
verified boolean This boolean is reflects whether or not the advisor has verified their email and set a password.
roleTitle string This describes the advisor's specific role, and the implied abilities that go with that.
completedOnboarding boolean This boolean is used to determine if the advisor should add banking information, and will be true in most cases when created via the API.
officeID number The ID of the office that the advisor has been assigned to.

Get an Advisor

Example Request

curl /api/public/v1/advisors/1 \
     -H "Authorization: Bearer advicepay_api_key"
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/advisors/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1
}

Required Permissions

User must be Managing Advisor or an Admin/Analyst under a Managing Advisor.

HTTP Request

GET /api/public/v1/advisors/<ID>

URL Parameters

Parameter Description
ID The ID of the advisor to fetch.

Response

Returns the requested advisor

Create an Advisor

Example Request

curl /api/public/v1/advisors \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "permission":"Advisor", "disableDirectLogin":false, "externalID": "abc123", "officeID": 1}' \
     -X POST
import "net/http"

type createAdvisorReq struct {
    Email              string `json:"email"`
    ExternalID         string `json:"externalID"`
    FirstName          string `json:"firstName"`
    LastName           string `json:"lastName"`
    Permission         string `json:"permission"`
    DisableDirectLogin bool   `json:"disableDirectLogin"`
    SSOSource          string `json:"ssoSource"`
    SSOID              string `json:"ssoID"`
    OfficeID           uint   `json:"officeID"`
}

// Marshall request data to JSON string
data := createAdvisorReq{
  Email:              "example@advicepay.com",
  ExternalID:         "abc123",
  FirstName:          "first",
  LastName:           "last",
  Permission:         "Advisor",
  DisableDirectLogin: false,
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/advisors", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1
}

Required Permissions

User must be Managing Advisor or an Admin under a Managing Advisor.

HTTP Request

POST /api/public/v1/advisors

Arguments

Value Required Type Description
email true string Email is validated for correct format and then for uniqueness in our database.
externalID false string No validation or formatting enforced. Note that this is not the same as ssoID. It is also up to the caller to ensure uniqueness of the value.
firstName true string Trailing or leading whitespaces will be trimmed.
lastName true string Trailing or leading whitespaces will be trimmed.
permission true string Must be one of the following: "Advisor", "Read-only Advisor", "No-login Advisor", or "Managing Advisor". "Advisor" gives full access to AdvicePay. "Read-only Advisor" gives login access but no power to invoice clients. "No-login Advisor" gives no login, and is completely managed by home office. "Managing Advisor" can see firm wide data and update firm settings.
disableDirectLogin false boolean If set to true, the advisor will only be able to login using SSO.
ssoSource conditional string If disableDirectLogin is set to true, this field is required to enable SSO login. The source is usually your company name.
ssoID conditional string If disableDirectLogin is set to true, this field is required to enable SSO login. The ID will be your unique idenitifier to create the SSO link between AdvicePay and your platform. Note that ssoID is not visible in the application UI.
officeID conditional number If included, the advisor will be assigned to the specified office.

Response

The newly created Advisor object, if the call succeeded. If the request failed, this call returns an error.

List Advisors

Example Request

curl /api/public/v1/advisors \
     -H "Authorization: Bearer advicepay_api_key" \
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/advisors", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":null,
      "email":"example@advicepay.com",
      "externalID":"abc123",
      "firstName":"first",
      "lastName":"last",
      "verified":true,
      "roleTitle":"Advisor",
      "completedOnboarding":true,
      "officeID":1
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

Required Permissions

User must be Managing Advisor or an Admin/Analyst under a Managing Advisor.

HTTP Request

GET /api/public/v1/advisors

Query Parameters

Parameter Default Type Description
page 1 number This will determine which page to return.
perPage 10 number This will determine the number of records to return (max is 100).
verified empty boolean Filter by whether advisors have verified their email and set a password (automatically set to true if login is SSO only).
email empty string Filter by advisor's email.
externalID empty string Filter by advisor's externalID.
officeID empty number Filter by advisor's office ID.

Response

Returns a list of advisors sorted by created_at in descending order

Clients

The Client Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{
    "Phone": "888-888-8888"
  }
}

Attributes

Value Type Description
id number This is the client's unique indentifier, and should be stored to do any future queries for data belonging to that client.
createdAt number This is the unix timestamp for when the client was created.
updatedAt number This is the unix timestamp for when the client was updated.
deletedAt number This is the unix timestamp for when the client was deleted.
email string This is validated for uniqueness.
externalID string This is used to specify an identifier from your system in the AdvicePay database.
firstName string Client's first name.
lastName string Client's last name.
invoiceDisplayName string The name to display on invoices. If left blank, the Client's first and last name will be used by default.
advisorID number This is the unique ID for the client's advisor.
verified boolean This boolean is reflects whether or not the client has verified their email and set a password.
wealthboxURL string This is used to easily go to Wealthbox from AdvicePay. This URL must begin with https://app.crmworkspace.com/contacts/.
metadata object Any additonal information added via a custom attribute will show here.

Get a Client

Example Request

curl /api/public/v1/clients/1 \
     -H "Authorization: Bearer advicepay_api_key"
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/clients/1", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{
    "Phone": "888-888-8888"
  }
}

HTTP Request

GET /api/public/v1/clients/<ID>

URL Parameters

Parameter Description
ID The ID of the client to fetch.

Response

Returns the requested client

Create a Client

Essential accounts are limited to 10 Clients.

Example Request

curl /api/public/v1/clients \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "advisorID":1, "externalID": "abc123"}' \
     -X POST
import "net/http"

type createClientReq struct {
    AdvisorID          uint
    Email              string
    ExternalID         string
    FirstName          string
    LastName           string
    InvoiceDisplayName string
    WealthboxURL       string
}

// Marshall request data to JSON string
data := createClientReq{
    AdvisorID:  1,
    Email:      "example@advicepay.com",
    ExternalID: "abc123",
    FirstName:  "first",
    LastName:   "last",
}
jsonData, err := json.Marshal(data)
// ...

// Build request
req, err := http.NewRequest("POST", "/api/public/v1/clients", bytes.NewBuffer(jsonData))
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{}
}

Required Permissions

User must be Managing Advisor, Full-Access Advisor or Admin.

HTTP Request

POST /api/public/v1/clients

Arguments

Value Required Type Description
email true string Email is validated for correct format and then for uniqueness in our database.
externalID false string No validation or formatting enforced. If the authorized user does not have permission to change Client IDs, any provided value will be ignored.
firstName true string Trailing or leading whitespaces will be trimmed.
lastName true string Trailing or leading whitespaces will be trimmed.
invoiceDisplayName false string The name to display on invoices. If left blank, the Client's first and last name will be used by default. Trailing or leading whitespaces will be trimmed.
advisorID false number This will create the client and advisor relationship. If not provided, it will default to the authorized user's ID (or Parent ID for Admin roles)
wealthboxURL false string This is used to easily go to Wealthbox from AdvicePay. This URL must begin with https://app.crmworkspace.com/contacts/.

Response

The newly created Client object, if the call succeeded. If the request failed, this call returns an error.

List Clients

Example Request

curl /api/public/v1/clients \
     -H "Authorization: Bearer advicepay_api_key" \
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/clients", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":null,
      "email":"example@advicepay.com",
      "externalID":"abc123",
      "firstName":"first",
      "lastName":"last",
      "advisorID":1,
      "verified":false,
      "invoiceDisplayName":"",
      "wealthboxURL":"",
      "metadata":{
        "Phone": "888-888-8888"
      }
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/clients

Query Parameters

Parameter Default Type Description
page 1 number This will determine which page to return.
perPage 10 number This will determine the number of records to return (max is 100).
advisorID empty number Filter by client advisor.
verified empty boolean Filter by whether clients have verified their email and set a password.
email empty string Filter by client's email.
name empty string Filter by client's first and/or last name. This is a case insensitive fuzzy match.
externalID empty string Filter by client's externalID.

Response

Returns a list of clients sorted by created_at in descending order

Invoices

The Invoice Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "clientID":1,
  "advisorID":2,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "dueDate":1551201267,
  "failedAt":1551201267,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "paymentMethod":"ach",
  "refundAmount":0,
  "refundDate":0,
  "status":"paid",
  "splitRepCode":"HN15448",
  "advisor": {},
  "client": {},
}

Attributes

Value Type Description
id number This is the invoice's unique indentifier.
createdAt number This is the unix timestamp for when the invoice was created.
updatedAt number This is the unix timestamp for when the invoice was updated.
deletedAt number This is the unix timestamp for when the invoice was deleted.
clientID number This is the ID of the client that the invoice belongs to.
advisorID number This is ID of the advisor that the invoice belongs to.
subscriptionID number This is the ID of the subscription that invoice belongs to for recurring payments.
amount number This is amount of the invoice in cents.
description string This is description of the invoice that the advisor provided.
dueDate number This is due date in unix time for the invoice set by the advisor.
failedAt number This is the date in unix time when the charge failed (set to 0 if not failed).
frequency string This is frequency of the invoice. It will be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", and "Semi-Annual recurring"
number number This is internal invoice number. Each advisor's invoice count starts att #1001.
paidDate number This is date in unix time that payment was made.
paymentMethod string This is the payment options given for the invoice. It will be one of: "ach", "ccd", or "either".
refundAmount number This is refund amount in cents if a refund has ocurreed on the invoice.
refundDate number This is refund date in unix time if a refund has ocurreed on the invoice.
status string This is status of the invoice. It will be one of: "unpaid" (no action has been taken), "paid" (invoice has been paid and funds have been transferred), "pending_payment" (user has submitted payment and money is transferring to bank account), "pending_processing" (user has submitted payment but subscription has not kicked off yet), "canceled", "refund_failed", "pending_approval", or "approval_rejected".
splitRepCode string This is split/rep code for the invoice that the advisor provided.
advisor object The advisor on the invoice.
client object The client on the invoice.

List Invoices

Example Request

curl /api/public/v1/invoices \
     -H "Authorization: Bearer advicepay_api_key" \
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/invoices", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":null,
      "clientID":1,
      "advisorID":2,
      "subscriptionID":1,
      "amount":1000,
      "description":"description",
      "dueDate":1551201267,
      "failedAt":1551201267,
      "frequency":"Monthly recurring",
      "number":1001,
      "paidDate":1551201267,
      "paymentMethod":"ach",
      "refundAmount":0,
      "refundDate":0,
      "status":"paid",
      "splitRepCode":"HN15448",
      "advisor": {},
      "client": {},
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/invoices

Query Parameters

Parameter Default Type Description
page 1 number This will determine which page to return.
perPage 10 number This will determine the number of records to return (max is 100).
status empty string Filter by invoice status. Must be one of: "unpaid", "paid", "failed", "pending_payment", "pending_processing", "canceled", "refunded", "refund_failed", "pending_approval", or "approval_rejected".
frequency empty string Filter by invoice frequency. Must be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", or "Semi-Annual recurring".
paidAfter empty number This is a unix timestamp to filter by paidDate.
advisorID empty number Filter by invoice advisor.
clientID empty number Filter by invoice client.

Response

Returns a list of invoices sorted by created_at in descending order

Download an Invoice

Example Request

curl -O -J /api/public/v1/invoices/1/download \
     -H "Authorization: Bearer advicepay_api_key"
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/invoices/1/download", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

N/A (PDF file will be created)

HTTP Request

GET /api/public/v1/invoices/<ID>/download

URL Parameters

Parameter Description
ID The ID of the invoice to download.

Response

Returns a PDF file for the invoice In the header of the response the "Content-Type" will be "application/octet-stream" and the "Content-Transfer-Encoding" is "binary"

Signers

The Signer Object

{
  "agreementID":1,
  "email":"example@advicepay.com",
  "name":"first last",
  "status":"signer_status_complete",
  "signedAt":1551201267,
  "signingOrder":0,
  "title":"Client",
}

Attributes

Value Type Description
agreementID number This is the unique indentifier of associated agreement.
email string This is the email of the signer.
name string This is the name of the signer.
status string This is status of the signature. It will be either an empty string "" or "signer_status_complete" when the signer has finished signing.
signedAt number This is a unix timestamp for when the signer signed.
signingOrder number If signing order is enabled on the agreement this number represents the rank of the signer in the order.
title string This is the title of the signature role on the document.

Agreements

The Agreement Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "clientID":1,
  "advisorID":2,
  "invoiceID":1,
  "status":"agreement_status_complete",
  "completedAt":1551201267,
  "signingOrderEnabled":true,
  "signers": [
    {
      "agreementID":1,
      "email":"example@advicepay.com",
      "name":"first last",
      "status":"signer_status_complete",
      "signedAt":1551201267,
      "signingOrder":0,
      "title":"Client",
    }
  ]
}

Attributes

Value Type Description
id number This is the agreement's unique indentifier.
createdAt number This is the unix timestamp for when the agreement was created.
updatedAt number This is the unix timestamp for when the agreement was updated.
deletedAt number This is the unix timestamp for when the agreement was deleted.
clientID number This is the ID of the client that the agreement was sent to.
advisorID number This is ID of the advisor that the agreement belongs to.
invoiceID number This is the ID of the invoice that is related to this agreement.
status string This is status of the agreement. It will be one of: "agreement_status_created" (no action has been taken), "agreement_status_opened" (a signer has opend the document), "agreement_status_complete" (all signers have signed the document), "agreement_status_voided" (the signature request has been canceled),
completedAt number This is the unix timestamp when all signers finished signing and the agreement was marked as complete.
signingOrderEnabled boolean This is true if the agreement was sent to one signer at a time in a particular signing order.
signers object list The signers on the agreement.

List Agreement

Example Request

curl /api/public/v1/agreements \
     -H "Authorization: Bearer advicepay_api_key" \
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/agreements", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":null,
      "clientID":1,
      "advisorID":2,
      "invoiceID":1,
      "status":"agreement_status_complete",
      "completedAt":1551201267,
      "signingOrderEnabled":true,
      "signers": [
        {
          "agreementID":1,
          "email":"example@advicepay.com",
          "name":"first last",
          "status":"signer_status_complete",
          "signedAt":1551201267,
          "signingOrder":0,
          "title":"Client",
        }
      ]
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/agreements

Query Parameters

Parameter Default Type Description
page 1 number This will determine which page to return.
perPage 10 number This will determine the number of records to return (max is 100).
advisorID empty number Filter by agreement advisor.
clientID empty number Filter by agreement client.
invoiceID empty number Filter by agreement invoice.
status empty string Filter by agreement status. Must be one of: "agreement_status_created", "agreement_status_opened", "agreement_status_complete", "agreement_status_voided".
completedAfter empty number This is a unix timestamp to filter by completedAt.

Response

Returns a list of agreements sorted by created_at in descending order

Download an Agreement

Example Request

curl -O -J /api/public/v1/agreements/1/download \
     -H "Authorization: Bearer advicepay_api_key"
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/agreements/1/download", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

N/A (PDF file will be returned)

HTTP Request

GET /api/public/v1/agreements/<ID>/download

URL Parameters

Parameter Description
ID The ID of the agreement to download.

Response

Returns a PDF file for the agreement. In the header of the response the "Content-Type" will be "application/octet-stream" and the "Content-Transfer-Encoding" is "binary".

Transfers

The transfers endpoint is currently only available to Enterprise accounts. Note: This endpoint is slow and may take over 10 seconds to return. Please adjust request timeouts acordingling.

The Transfer Object

{
  "id": "Kok1FeZg9HVyHl4ufXtHl6xBfOS",
  "status": "paid",
  "grossAmount": 1400,
  "bankDeposit": 1321,
  "arrivalDate": 1551201267,
  "paymentCount": 1,
  "feeOverride": 0,
  "transactions": [
    {
      "id": "1FK4P7HVyHl4ufXt73dCbyme",
      "transferID": "Kok1FeZg9HVyHl4ufXtHl6xBfOS",
      "transactionType": "charge",
      "paymentType": "CC",
      "grossAmount": 1400,
      "feeAP": 79,
      "feeOverride": 0,
      "total": 1321,
      "paidDate": 1551201267,
      "clientName": "first last",
      "clientExternalID": "",
      "advisorName": "first last",
      "advisorEmail": "example@advicepay.com",
      "advisorExternalID": "",
      "invoiceID": 1,
      "invoiceNum": 1001,
      "invoiceType": "Single Payment",
      "recurringStartDate": 0,
      "recurringEndDate": 0,
      "invoiceDescription": "description",
      "splitRepCode": ""
    }
  ]
}

Attributes

Value Type Description
id string This is the transfer's unique indentifier.
status string This is status of the transfer. It will be one of: "paid" (funds have been successfully transferred), "pending" (waiting to be submitted to the bank), "in_transit" (submitted to the bank), "failed", "canceled".
grossAmount number This is the amount of the total transaction charges in cents.
bankDeposit number This is the amount for deposit in cents.
arrivalDate number This is the unix timestamp for arival of deposit to bank account.
paymentCount number This is the number of transactions included in the transfer.
feeOverride number This is the calculated percentage firm fee amount. Percentage set under enterprise firm settings.
transactions object list This is the list of transactions included in the transfer.

The Transaction Object

Attributes

Value Type Description
id string This is the transaction's unique indentifier.
transferID string This is the ID of the transfer that the transaction belongs to.
transactionType string This is the type of the transaction. Typically one of: "charge", "payment", "refund", "payment_failure_refund"
paymentType string This is the type of payment used for the transaction. It will be either "CC" (credit card) or "ACH" (bank account)
grossAmount number This is the amount chaged in cents.
feeAP number This is the amount of the transaction fee.
feeOverride number This is the calculated percentage firm fee amount. Percentage set under enterprise firm settings.
total number This is the amount for deposit in cents.
paidDate number This is the unix timestamp for when the charge was paid.
clientName string This is the first and last name of the client.
clientExternalID string This is the optional id feild on the client object.
advisorName string This is the first and last name of the advisor on the invoice.
advisorEmail string This is the email of the advisor on the invoice.
advisorExternalID string This is the optional id feild on the advisor object.
invoiceID number This is AdvicePay's unique internal invoice ID.
invoiceNum number This is the invoice number shown on the invoice. Each advisor's invoice count starts at #1001.
invoiceType string This is the type of the invoice. It will be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring",
recurringStartDate number This is the unix timestamp for when the the recurring payment was started.
recurringEndDate number This is the unix timestamp for when the the recurring payment ends.
invoiceDescription string This is the description on the invoice.
splitRepCode string This is the split/rep code on the invoice.

List Transfers

Required Permissions

User must be Managing Advisor or an Admin/Analyst under a Managing Advisor.

Example Request

curl /api/public/v1/transfers \
     -H "Authorization: Bearer advicepay_api_key" \
import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/transfers", nil)
// ...

// Do request
resp, err := http.DefaultClient.Do(req)
// ...

Example Response

{
  "items": [
    {
      "id": "Kok1FeZg9HVyHl4ufXtHl6xBfOS",
      "status": "paid",
      "grossAmount": 1400,
      "bankDeposit": 1321,
      "arrivalDate": 1551201267,
      "paymentCount": 1,
      "feeOverride": 0,
      "transactions": [
        {
          "id": "1FK4P7HVyHl4ufXt73dCbyme",
          "transferID": "Kok1FeZg9HVyHl4ufXtHl6xBfOS",
          "transactionType": "charge",
          "paymentType": "CC",
          "grossAmount": 1400,
          "feeAP": 79,
          "feeOverride": 0,
          "total": 1321,
          "paidDate": 1551201267,
          "clientName": "first last",
          "clientExternalID": "",
          "advisorName": "first last",
          "advisorEmail": "example@advicepay.com",
          "advisorExternalID": "",
          "invoiceID": 1,
          "invoiceNum": 1001,
          "invoiceType": "Single Payment",
          "recurringStartDate": 0,
          "recurringEndDate": 0,
          "invoiceDescription": "description",
          "splitRepCode": ""
        }
      ]
    },
    ...
  ]
}

HTTP Request

GET /api/public/v1/transfers

Query Parameters

Parameter Default Type Description
arrivalAfter empty number This is a unix timestamp to filter for transfers with arrivalDate after this timestamp.
arrivalBefore empty number This is a unix timestamp to filter for transfers with arrivalDate before this timestamp.

Response

Returns a list of transfers sorted by arrivalDate in descending order

Pagination

{
  "items": [{},{},...],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list invoices. Most list API methods share a common structure, taking these two parameters: page and perPage.

The structure if elements in items will change depending on the endpoint, but the rest of the payload structure will be the same.

Errors

AdvicePay uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with AdvicePay's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., an email is not unique) include an error message that briefly explains the error reported.

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong or your permissions are not set.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
409 Conflict -- likely that you are trying to create or update something with a non-unique email.
429 Too Many Requests -- Look at the following headers for more details: "X-RateLimit-Reset", "X-RateLimit-Remaining", and "X-RateLimit-Limit".
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
Example Responses

{
  "code":409,
  "message":"Email example@advicepay.com is already in use",
  "details":null
}

{
  "code":400,
  "message":"permission: acceptable_advisor_permission",
  "details":{"Permission":"acceptable_advisor_permission"}
}
Value Description
code This is the http status code.
message This is the error message.
details This is used to describe data validation issues in a map with the failed request value as the key and the validation rule that failed as the value.

Validation Messages

Message Meaning
acceptable_invoice_status Must be one of: "unpaid", "paid", "failed", "pending_payment", "pending_processing", "canceled", "refunded", "refund_failed", "pending_approval", or "approval_rejected".
acceptable_frequency Must be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", or "Semi-Annual recurring".
acceptable_advisor_permission Must be one of: "Advisor", "Read-only Advisor", "No-login Advisor", or "Managed Advisor".
acceptable_user_permission Must be one of: "Admin" or "Analyst".

Single Sign On

You will need to have your public certificate installed on an AdvicePay server before you are able to make SSO requests.

We've built a sandbox using our implementation so that it is easy to send test requests to localhost:<PORT>/auth/sso. You simply need to add your cert to a the project's root. There is no need to install go, unless you want to modify the library and build it yourself. Running the binary will start a server at localhost:<PORT>`. If you need access you can request it here.

Requesting Access

This endpoint creates a session using a link between a 3rd party system (identity provider) and AdvicePay (service provider). If AdvicePay has never seen the user before or the user was not created with a ssoID, they will need to login once to build the relationship between identity and service provider.

HTTP Request

POST /auth/sso

Query Parameters

Parameter Required Description
source true The company slug used to determine which certificate to validate against.

Arguments

Value Required Type Description
SAMLResponse true string This is a base64 encoded string, and is often called the assertion.
RelayState false string This can be passed as a relative URL to specify where the user gets redirected to after a successful SAML assertion.