NAV
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.

Authorization

Example Request

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)

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 authorization available: API token (Deprecated) and OAuth 2.0.

OAuth 2.0 Authorization Code

The Authorization Code flow is useful for user-level integrations where AdvicePay users are within different accounts. OAuth clients for firms with developer access can be added within the developer console. OAuth clients for our integration partners 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. 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 and refresh token using an authorization code
  4. Your site refreshes the access token and the refresh token using a refresh token
  5. Your site makes API calls using the access token

1. Requesting authorization from the user

Example Request

curl /oauth2/authorize?client_id=yourClientID&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth&scope=all&state=xj15na

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/oauth2/authorize?client_id=yourClientID&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth&scope=all&state=xj15na", nil)
// ...

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

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 and refresh token using your authorization code

Example Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=362ad374-735c-4f69-aa8e-bf384f8602de&redirect_uri=http://example.com/oauth&client_id=yourClientID&client_secret=yourClientSecret" /oauth2/access_token

import "net/http"

// Build request
req, err := http.NewRequest("POST", "/oauth2/access_token", "grant_type=authorization_code&code=362ad374-735c-4f69-aa8e-bf384f8602de&redirect_uri=http://example.com/oauth&client_id=yourClientID&client_secret=yourClientSecret")
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
// ...

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

Example Response

{
  "access_token": "228c9f52-c003", 
  "access_token_expires_at": 1606942087, 
  "refresh_token": "dsfslBBDFSFS343", 
  "refresh_token_expires_at": 1609534087, 
  "scope": scope, 
  "token_type": "bearer"
}

HTTP Request

POST /oauth2/access_token

Form Fields

Parameter Description
client_id Your provisioned client ID
client_secret Your provisioned client secret (required when authentication method is Client Secret POST)
client_assertion_type The assertion type for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
client_assertion The JWT assertion for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
code The authorization code you received at the redirect URI in the previous step
grant_type The OAuth 2.0 grant type ("authorization_code" should be used when using an authorization code to retrieve the access token)
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 and refresh token for the user. These tokens should be stored securely and not be exposed outside of making API calls to AdvicePay. Access tokens expire after 5 minutes. Refresh tokens are single-use and expire after 30 days.

4. Refreshing the access token and refresh token using your refresh token

Example Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token=dsfslBBDFSFS343&client_id=yourClientID&client_secret=yourClientSecret" /oauth2/access_token

import "net/http"

// Build request
req, err := http.NewRequest("POST", "/oauth2/access_token", "grant_type=refresh_token&refresh_token=dsfslBBDFSFS343&client_id=yourClientID&client_secret=yourClientSecret")
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
// ...

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

Example Response

{
  "access_token": "228c9f52-c003", 
  "access_token_expires_at": 1606942087, 
  "refresh_token": "babadfdff55343434", 
  "refresh_token_expires_at": 1609534087, 
  "scope": scope, 
  "token_type": "bearer"
}

HTTP Request

POST /oauth2/access_token

Form Fields

Parameter Description
client_id Your provisioned client ID
client_secret Your provisioned client secret (required when authentication method is Client Secret POST)
client_assertion_type The assertion type for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
client_assertion The JWT assertion for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
refresh_token The user's refresh token
grant_type The OAuth 2.0 grant type ("refresh_token" should be used when using a refresh token to refresh the access token)

You will get a JSON response containing an access token and a new refresh token for the user. These tokens should be stored securely and not be exposed outside of making API calls to AdvicePay. Access tokens expire after 5 minutes. Refresh tokens are single-use and expire after 30 days.

5. Making API calls with your access token

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

Authorization: Bearer 228c9f52-c003

OAuth 2.0 Client Credentials

The Client Credentials flow is useful for enterprise account owner accounts acting on behalf of an integrating system. OAuth clients for firms with developer access can be added within the developer console. To enable the client credentials flow for your OAuth client, use the "Enable OAuth 2.0 Client Credentials Flow" toggle. The flow to authorize users for your app is:

  1. Your site requests an access token using the client ID and client secret
  2. Your site makes API calls using the access token

1. Requesting an access token using your client ID and client secret

Example Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=yourClientID&client_secret=yourClientSecret" /oauth2/access_token

import "net/http"

// Build request
req, err := http.NewRequest("POST", "/oauth2/access_token", "grant_type=client_credentials&client_id=yourClientID&client_secret=yourClientSecret")
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
// ...

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

Example Response

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

HTTP Request

POST /oauth2/access_token

Form Fields

Parameter Description
client_id Your provisioned client ID
client_secret Your provisioned client secret (required when authentication method is Client Secret POST)
client_assertion_type The assertion type for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
client_assertion The JWT assertion for authentication (required when authentication method is Client Secret JWT or Private Key JWT)
grant_type The OAuth 2.0 grant type ("client_credentials" should be used when using the client credentials flow to retrieve the access token)

You will get a JSON response containing an access token for the account owner. This token should be stored securely and not be exposed outside of making API calls to AdvicePay. Access tokens expire after 5 minutes.

2. Making API calls with your access token

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

Authorization: Bearer 228c9f52-c003

API Token (Deprecated)

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 2.0 Authentication Methods

AdvicePay supports multiple authentication methods for obtaining an OAuth 2.0 token, depending on your needs. The authentication method can be set for your OAuth client in your developer dashboard.

Client Secret POST

This is the least secure authentication method because it involves sending the client secret in the body of each request to obtain a token. When you make the request to the access_token endpoint, simply include your provisioned client secret as the client_secret parameter in the request body.

Client Secret JWT

This is more secure because your client secret stays on your server. You'll generate a JWT and sign it with your client secret using HS256. When you make the request to the access_token endpoint, include the signed JWT as the client_assertion parameter in the request body. You'll also need to set the client_assertion_type parameter in the request body to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Private Key JWT

This is the most secure way of obtaining a token. You'll use an asymmetric key pair for authentication. You'll generate a JWT and sign it with your private key using RS256. To use the Private Key JWT authentication method, you will need to upload your public key in your developer dashboard. We'll verify each request with the public key. When you make the request to the access_token endpoint, include the signed JWT as the client_assertion parameter in the request body. You'll also need to set the client_assertion_type parameter in the request body to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

JWT Format

The JWT Format

Claim Description
aud Required. The URL of the resource you're authenticating to. This will generally be https://app.advicepay.com/oauth2/access_token.
exp Required. The unix timestamp for the expiration time of the token. We recommend keeping this short. If the request is received after the time indicated by exp, it will be rejected.
jti Optional. The token identifier. If jti is used, AdvicePay will prevent the same jti from being used more than once. This mitigates replay attacks and is highly recommended.
iat Required. The unix timstamp for when the token was issued. If the request is received before the time indicated by iat, it will be rejected.
iss Required. The issuer of the token. This should always be your client ID.
sub Required. The subject of the token. This should also always be your client ID.

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":0,
  "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.

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":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "parentID":1,
  "roleTitle":"Admin",
  "parent":{}
}

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.
parent object The parent advisor of the admin.

List Admins

Example Request

curl /api/public/v1/admins \
      -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

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

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

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "email":"example@advicepay.com",
      "firstName":"first",
      "lastName":"last",
      "parentID":1,
      "roleTitle":"Admin",
      "parent":{}
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

Required Permissions

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

HTTP Request

GET /api/public/v1/admins

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).
roleTitle empty string Filter by whether the admin is a (developer, admin, or analyst).
email empty string Filter by an admins's email.
parentID empty string Filter by admins parentID.

Response

Returns a list of admins sorted by created_at in descending order

Get an Admin

Example Request

curl /api/public/v1/admins/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

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

Required Permissions

User must be an Advisor.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the admin to fetch.

Response

Returns the requested admin

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"`
  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":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "parentID":1,
  "roleTitle":"Admin",
  "parent":{}
}

Required Permissions

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

HTTP Request

POST /api/public/v1/admins

Arguments

Value Required Type Description
email true string Email is validated for correct format and then to ensure it is unique for the given parentID.
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. Admins may be associated with any advisor with read and write permissions (Full-Access Advisor, Managing Advisor, Advisor). Analysts may be associated with any advisor with read permissions (Full-Access Advisor, Managing Advisor, Advisor, Read-only Advisor).
disableDirectLogin false boolean If set to true, the admin will only be able to login using SSO.
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.

Response

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

Update an Admin

Example Request

curl /api/public/v1/admins/1 \
      -H "Authorization: Bearer advicepay_api_key" \
      -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "permission":"Admin", "disableDirectLogin": true, "ssoID": "12345"}' \
      -X PUT

import "net/http"

type updateAdminReq struct {
  Email              string `json:"email"`
  FirstName          string `json:"firstName"`
  LastName           string `json:"lastName"`
  Permission         string `json:"permission"`
  DisableDirectLogin bool   `json:"disableDirectLogin"`
  SSOID              string `json:"ssoID"`
}

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

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

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

Example Response

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

Required Permissions

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the admin to update.

Arguments

Value Required Type Description
email false string Email is validated for correct format and then for uniqueness in our database. If this is not sent, the existing email address will be maintained.
firstName false string Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing first name will be maintained.
lastName false string Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing last name will be maintained.
permission false 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. If this is not sent on the request, the existing permission will be maintained.
disableDirectLogin false boolean If set to true, the admin will only be able to login using SSO. If this is not sent on the request, the existing setting for disable direct login will be maintained.
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. If this is not sent on the request, the existing SSO ID will be maintained.

Response

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

Delete an Admin

Example Request

curl /api/public/v1/admins/1 \
      -H "Authorization: Bearer advicepay_api_key" \
      -X DELETE

import "net/http"

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

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

Example Response

{
  "id":1
}

Required Permissions

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

HTTP Request

DELETE /api/public/v1/admins/<ID>

URL Parameters

Parameter Description
ID The ID of the admin to delete.

Response

Returns the ID of the deleted admin

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":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "metadata":{
    "Phone": "888-888-8888"
  }
}

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.
metadata object Any additonal information added via a custom attribute will show here.

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":0,
      "email":"example@advicepay.com",
      "externalID":"abc123",
      "firstName":"first",
      "lastName":"last",
      "verified":true,
      "roleTitle":"Advisor",
      "completedOnboarding":true,
      "officeID":1,
      "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

Required Permissions

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

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

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":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "metadata":{
    "Phone": "888-888-8888"
  }
}

Required Permissions

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

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"`
  SSOID              string `json:"ssoID"`
  OfficeID           uint   `json:"officeID"`
  Metadata           map[string]interface{}
}

// Marshall request data to JSON string
data := createAdvisorReq{
  Email:              "example@advicepay.com",
  ExternalID:         "abc123",
  FirstName:          "first",
  LastName:           "last",
  Permission:         "Advisor",
  DisableDirectLogin: false,
  Metadata:           map[string]interface{}{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": []string{"a", "b", "c"}},
}
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":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
}

Required Permissions

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

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", "Managing Advisor", or "Full-access 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 office-wide data. "Full-access Advisor" can see firm-wide data and update firm settings (note: Full-access Advisor permissions are only available to the Account Owner for enterprise firms. The request will be rejected if this is set on an enterprise advisor.).
disableDirectLogin false boolean If set to true, the advisor will only be able to login using SSO.
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.
officeID conditional number If included, the advisor will be assigned to the specified office.
metadata false object This is used to populate the metadata for the advisor.

Response

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

Update an Advisor

Example Request

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

import "net/http"

type updateAdvisorReq 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"`
  SSOID              string `json:"ssoID"`
  OfficeID           uint   `json:"officeID"`
  Metadata           map[string]interface{}
}

// Marshall request data to JSON string
data := updateAdvisorReq{
  Email:              "example@advicepay.com"
  ExternalID:         "abc123",
  FirstName:          "first",
  LastName:           "last",
  Permission:         "Advisor",
  DisableDirectLogin: false,
  Metadata:           map[string]interface{}{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": []string{"a", "b", "c"}},
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1561422442,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}
}

Required Permissions

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the advisor to update.

Arguments

Value Required Type Description
email false string Email is validated for correct format and then for uniqueness in our database. If this is not sent, the existing email address will be maintained.
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. If this is not sent on the request, the existing external ID will be maintained.
firstName false string Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing first name will be maintained.
lastName false string Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing last name will be maintained.
permission false string Must be one of the following: "Advisor", "Read-only Advisor", "No-login Advisor", "Managing Advisor", or "Full-access 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 office-wide data. "Full-access Advisor" can see firm-wide data and update firm settings. If this is not sent on the request, the existing permission will be maintained.
disableDirectLogin false boolean If set to true, the advisor will only be able to login using SSO. If this is not sent on the request, the existing setting for disable direct login will be maintained.
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. If this is not sent on the request, the existing SSO ID will be maintained.
officeID conditional number If included, the advisor will be assigned to the specified office. If this is not sent on the request, the existing office ID will be maintained.
metadata false object This is used to populate the metadata for the advisor. If this is not sent on the request, the existing metadata will be maintained. If this is on the request, all existing metadata will be deleted.

Response

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

Delete an Advisor

Example Request

curl /api/public/v1/advisors/1 \
     -H "Authorization: Bearer advicepay_api_key" \
     -X DELETE

import "net/http"

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

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

Example Response

{
  "id":1
}

Required Permissions

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the advisor to delete.

Response

Returns the ID of the deleted advisor

Agreements

The Agreement Object

{
  "id":1,
  "completedAt":1551201267,
  "createdAt":1551201267,
  "deletedAt":0,
  "finalizedAt": 1551201268,
  "updatedAt":1551201268,
  "clientID":1,
  "advisorID":2,
  "engagementID":3,
  "invoiceID":1,
  "status":"agreement_status_complete",
  "signingOrderEnabled":true,
  "signers": [
    {
      "agreementID":1,
      "email":"example@advicepay.com",
      "name":"first last",
      "status":"signer_status_complete",
      "signedAt":1551201267,
      "completedAt":1551201267,
      "signingOrder":0,
      "title":"Client",
      "externalID":"abc123",
    }
  ],
  "template": {
    "name": "ExampleTemplate",
    "description": "Example eSign Template"
  }
}

Attributes

Value Type Description
id number This is the agreement's unique indentifier.
completedAt number This is the unix timestamp when all signers finished signing and the agreement was marked as complete. For uploaded documents, this is populated via the AdvicePay UI when the advisor uploads them.
createdAt number This is the unix timestamp for when the agreement was created.
deletedAt number This is the unix timestamp for when the agreement was deleted.
finalizedAt number This is the unix timestamp for when the agreement was finalized and marked as ready for download. This will never change once it is set. For eSigned documents, this is the date the last signer signs the document. For uploaded documents, this is the date the document was uploaded.
updatedAt number This is the unix timestamp for when the agreement was updated.
clientID number This is the unique AdvicePay ID of the client that the agreement was sent to. Since signer emails can be entered manually, it is possible for the Client ID to be 0, which indicates that no signers match up with a client record. An example scenario where a client record wouldn't exist is a document that needs to be signed by the advisor and the home office.
advisorID number This is the unique AdvicePay ID of the advisor that created the agreement.
engagementID number This is the ID of the engagement that the agreement belongs to.
invoiceID number This is the ID of the invoice that is related to the 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 opened the document), "agreement_status_complete" (all signers have signed the document), "agreement_status_voided" (the signature request has been canceled), "agreement_status_draft" (the signature request needs to be completed before sending)
signingOrderEnabled boolean This is true if the agreement was sent to one signer at a time in a particular signing order.
fileNames string list For agreements uploaded to AdvicePay, the collection of file names of the uploaded PDFs. This will be empty if the agreement wasn't uploaded as a PDF.
signers object list The signers on the agreement. This will be empty if the agreement was uploaded as a PDF.
template object The template on the agreement. Warning: this will be null if the agreement was uploaded as a PDF.

List Agreements

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,
      "completedAt":1551201267,
      "createdAt":1551201267,
      "deletedAt":0,
      "finalizedAt":1551201268,
      "updatedAt":1551201268,
      "clientID":1,
      "advisorID":2,
      "engagementID":3,
      "invoiceID":1,
      "status":"agreement_status_complete",
      "signingOrderEnabled":true,
      "signers": [
        {
          "agreementID":1,
          "email":"example@advicepay.com",
          "name":"first last",
          "status":"signer_status_complete",
          "signedAt":1551201267,
          "completedAt":1551201267,
          "signingOrder":0,
          "title":"Client",
          "externalID":"abc123",
        }
      ],
      "template": {
        "name": "ExampleTemplate",
        "description": "Example eSign Template"
      }
    },
    {
      "id": 2,
      "completedAt": 1663740000,
      "createdAt": 1664483269,
      "deletedAt": 0,
      "finalizedAt": 1664483269,
      "updatedAt": 1664483269,
      "advisorID": 2,
      "clientID": 1,
      "engagementID": 3,
      "invoiceID": 0,
      "templateID": 0,
      "status": "agreement_status_complete",
      "signingOrderEnabled": false,
      "fileNames": [
          "Blank+Document.pdf"
      ],
      "signers": [],
      "template": null
    }
    ...
  ],
  "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.
engagementID empty number Filter by agreement engagement.
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. For most public API operations, we recommend using finalizedAfter.
completedBefore empty number This is a unix timestamp to filter by completedAt. For most public API operations, we recommend using finalizedBefore.
finalizedAfter empty number This is a unix timestamp to filter by finalizedAt.
finalizedBefore empty number This is a unix timestamp to filter by finalizedAt.
updatedAfter empty number This is a unix timestamp to filter by updatedAt.
updatedBefore empty number This is a unix timestamp to filter by updatedAt.

Response

Returns a list of agreements sorted by created_at in descending order

Get an Agreement

Example Request

curl /api/public/v1/agreements/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "deletedAt":0,
  "completedAt":1551201267,
  "finalizedAt":1551201268,
  "updatedAt":1551201268,
  "clientID":1,
  "advisorID":2,
  "engagementID":3,
  "invoiceID":1,
  "status":"agreement_status_complete",
  "signingOrderEnabled":true,
  "fileNames": [],
  "signers": [
    {
      "agreementID":1,
      "email":"example@advicepay.com",
      "name":"first last",
      "status":"signer_status_complete",
      "signedAt":1551201267,
      "completedAt":1551201267,
      "signingOrder":0,
      "title":"Client",
      "externalID":"abc123",
    }
  ],
  "template": {
    "name": "ExampleTemplate",
    "description": "Example eSign Template"
  }
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the agreement to fetch.

Response

Returns the requested agreement

Download an Agreement

Example Request

curl -O -J /api/public/v1/agreements/1/download?expect=json \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "data":"Base64-encoded Data Here",
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the agreement to download.

Query Parameters

Parameter Default Type Description
expect binary string The expected response type. Must be one of "binary" (default) or "json".

Response

Returns a PDF file for the agreement. If "expect" query parameter is "binary" or omitted, the response will contain the binary representation of the file. The response header will have a "Content-Type" of "application/octet-stream" and "Content-Transfer-Encoding" of "binary". If "expect" query parameter is "json", the response will contain a file transfer object with a Base64-encoded representation of the file.

Clients

The Client Object

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

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.
advisor object The advisor of the client.

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":0,
      "email":"example@advicepay.com",
      "externalID":"abc123",
      "firstName":"first",
      "lastName":"last",
      "advisorID":1,
      "verified":false,
      "invoiceDisplayName":"",
      "wealthboxURL":"",
      "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]},
      "advisor":{}
    },
    ...
  ],
  "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

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":0,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{
    "Phone": "888-888-8888"
  },
  "advisor":{}
}

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", "metadata": {"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}}' \
     -X POST

import "net/http"

type createClientReq struct {
  AdvisorID          uint
  Email              string
  ExternalID         string
  FirstName          string
  LastName           string
  InvoiceDisplayName string
  WealthboxURL       string
  Metadata           map[string]interface{}
}

// Marshall request data to JSON string
data := createClientReq{
  AdvisorID:  1,
  Email:      "example@advicepay.com",
  ExternalID: "abc123",
  FirstName:  "first",
  LastName:   "last",
  Metadata: map[string]interface{}{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": []string{"a", "b", "c"}},
}
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":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]},
  "advisor":{}
}

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 to ensure it is unique for the given advisorID.
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)
disableDirectLogin false boolean If set to true, the client will only be able to login using SSO.
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.
wealthboxURL false string This is used to easily go to Wealthbox from AdvicePay. This URL must begin with https://app.crmworkspace.com/contacts/.
metadata false object This is used to populate the metadata for the client.

Response

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

Update a Client

Example Request

curl /api/public/v1/clients/2 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "advisorID":1, "externalID": "abc123", "metadata": {"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]}}' \
     -X PUT

import "net/http"

type updateClientReq struct {
  AdvisorID          uint
  Email              string
  ExternalID         string
  FirstName          string
  LastName           string
  InvoiceDisplayName string
  WealthboxURL       string
  Metadata           map[string]interface{}
}

// Marshall request data to JSON string
data := updateClientReq{
  AdvisorID:  1,
  Email:      "example@advicepay.com",
  ExternalID: "abc123",
  FirstName:  "first",
  LastName:   "last",
  Metadata: map[string]interface{}{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": []string{"a", "b", "c"}},
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id":2,
  "createdAt":1551201267,
  "updatedAt":1551201278,
  "deletedAt":0,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "invoiceDisplayName":"",
  "advisorID":1,
  "verified":false,
  "wealthboxURL":"",
  "metadata":{"Input Field": "Test Input", "Dropdown Field": "Option 2", "Multi Tag Field": ["a", "b", "c"]},
  "advisor":{}
}

Required Permissions

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the client to update.

Arguments

Value Required Type Description
email false string Email is validated for correct format and then for uniqueness in our database. Note that client emails can only be updated prior to the client or their authorized users creating a payment method. If this is not sent on the request, the existing email will be maintained.
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. If this is not sent on the request, the existing external ID will be maintained.
firstName false string Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing first name will be maintained.
lastName false string Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing last name will be maintained.
invoiceDisplayName false string The name to display on invoices. Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing invoice display name will be maintained.
advisorID false number This will create the client and advisor relationship. If this is not sent on the request, the existing advisor ID will be maintained.
disableDirectLogin false boolean If set to true, the client will only be able to login using SSO.
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.
wealthboxURL false string This is used to easily go to Wealthbox from AdvicePay. This URL must begin with https://app.crmworkspace.com/contacts/. If this is not sent on the request, the existing Wealthbox URL will be maintained.
metadata false object This is used to populate the metadata for the client. If this is not sent on the request, the existing metadata will be maintained. If this is on the request, all existing metadata will be deleted.

Response

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

Custom Attributes

The Custom Attribute Object

{
    "id": 1,
    "createdAt": 1588366251,
    "updatedAt": 1588623099,
    "deletedAt": 0,
    "name": "My Text Field",
    "type": "text",
    "options": [],
    "description": "Enter text in this field.",
    "order": 1,
    "required": true,
    "visible": true
}

Attributes

Value Type Description
id number This is the attribute's unique indentifier.
createdAt number This is the unix timestamp for when the attribute was created.
updatedAt number This is the unix timestamp for when the attribute was updated.
deletedAt number This is the unix timestamp for when the attribute was deleted.
name string This is the name of the attribute (The field label on the UI).
type string This is the type of the attribute. Values for this can be "text" for text inputs, "select" for dropdowns, or "tags" for multi-tag fields.
options string list This is the list of options for the "select" attribute type.
description string This is the friendly description of how to use the attribute.
order number This is the order that the field appears on the screen in the UI.
required boolean This indicates whether an entry in field is required.
visible boolean This indicates that the field is hidden on the UI.

List Client Attributes

Example Request

curl /api/public/v1/client_attributes \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

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

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

Example Response

{
    "items": [
        {
            "id": 1,
            "createdAt": 1588366251,
            "updatedAt": 1588623099,
            "deletedAt": 0,
            "name": "My Text Field",
            "type": "text",
            "options": [],
            "description": "Enter text in this field.",
            "order": 1,
            "required": true,
            "visible": true
        },
        {
            "id": 2,
            "createdAt": 1604087954,
            "updatedAt": 1604087954,
            "deletedAt": 0,
            "name": "My Dropdown",
            "type": "select",
            "options": [
                "Option 1",
                "Option 2"
            ],
            "description": "Select a value.",
            "order": 2,
            "required": true,
            "visible": true
        },
        {
            "id": 3,
            "createdAt": 1604088359,
            "updatedAt": 1604088359,
            "deletedAt": 0,
            "name": "My Multi-tag",
            "type": "tags",
            "options": [],
            "description": "Tag this field with multiple values.",
            "order": 3,
            "required": true,
            "visible": true
        }
    ],
    "page": 1,
    "perPage": 10,
    "totalItems": 3,
    "totalPages": 1,
    "unknownTotal": false,
    "hasMore": false
}

HTTP Request

GET /api/public/v1/client_attributes

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 custom attributes sorted by created_at in descending order

List Advisor Attributes

Example Request

curl /api/public/v1/advisor_attributes \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

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

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

Example Response

{
    "items": [
        {
            "id": 1,
            "createdAt": 1588366251,
            "updatedAt": 1588623099,
            "deletedAt": 0,
            "name": "My Text Field",
            "type": "text",
            "options": [],
            "description": "Enter text in this field.",
            "order": 1,
            "required": true,
            "visible": true
        },
        {
            "id": 2,
            "createdAt": 1604087954,
            "updatedAt": 1604087954,
            "deletedAt": 0,
            "name": "My Dropdown",
            "type": "select",
            "options": [
                "Option 1",
                "Option 2"
            ],
            "description": "Select a value.",
            "order": 2,
            "required": true,
            "visible": true
        },
        {
            "id": 3,
            "createdAt": 1604088359,
            "updatedAt": 1604088359,
            "deletedAt": 0,
            "name": "My Multi-tag",
            "type": "tags",
            "options": [],
            "description": "Tag this field with multiple values.",
            "order": 3,
            "required": true,
            "visible": true
        }
    ],
    "page": 1,
    "perPage": 10,
    "totalItems": 3,
    "totalPages": 1,
    "unknownTotal": false,
    "hasMore": false
}

HTTP Request

GET /api/public/v1/advisor_attributes

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 custom attributes sorted by created_at in descending order

Deliverables

The Deliverable Template Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"My Template"
  "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},
  "esignTemplateExternalID":"ext123"
  "dueDateType":"calculate"
  "dueDateIntervalType":"years",
  "dueDateInterval":1,
  "dueDateTrigger":"invoice_paid"
  "recurring":true
  "recurringIntervalType":"years"
  "recurringInterval":1
  "recurringTrigger":"last_completed_deliverable"
  "maxRecurrence":2
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
}

Attributes

Value Type Description
id number This is the template's unique indentifier, and should be stored to do any future queries for data belonging to that template.
createdAt number This is the unix timestamp for when the template was created.
updatedAt number This is the unix timestamp for when the template was updated.
deletedAt number This is the unix timestamp for when the template was deleted.
name string The name of the template.
detailedEvidenceTypes object The types of evidence that can be used for the template. Valid keys are "file", "url", "esign", "notes" and "attestation". Each has an object with 2 values visible and required. Visible determines whether or not they can see/submit that evidence type.
esignTemplateExternalID string The eSign template that will be used for evidence if "esign" is included in detailedEvidenceTypes.
dueDateType string Valid values are "specify", "calculate".
dueDateIntervalType string This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
dueDateInterval number This is the interval specified in dueDateIntervalType units.
dueDateTrigger string This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".
recurring boolean Recurring deliverables will automatically create a new deliverable when triggered and assign it to the same advisor.
recurringIntervalType string This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
recurringInterval number This is the interval specified in recurringIntervalType units.
recurringTrigger string This is the trigger used to calculate when the deliverable is due. Valid value "last_completed_deliverable".
maxRecurrence number Total number of deliverables owed.
allowedFileTypes string list The only file types that can be submitted on deliverables. Valid file types are [".png",".jpg",".pdf",".docx"]

The Deliverable Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":false,
  "notes":"",
  "urls":[],
  "fileNames":[],
  "allowedFileTypes":[],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

Attributes

Value Type Description
id number This is the deliverable's unique indentifier, and should be stored to do any future queries for data belonging to that deliverable.
createdAt number This is the unix timestamp for when the deliverable was created.
updatedAt number This is the unix timestamp for when the deliverable was updated.
deletedAt number This is the unix timestamp for when the deliverable was deleted.
advisorID number This is the unique identifier of the advisor that the deliverable was assigned to.
clientID number This is the unique identifier of the client that the deliverable is associated with.
engagementID number This is the unique identifier of the engagement that the deliverable belongs to.
status string This is the status of the deliverable. Valid values are "open", "complete", "upcoming", and "past_due".
templateName string The name of the template used to create the deliverable.
triggerDate number This is the unix timestamp for when the deliverable was triggered.
dueDate number This is the unix timestamp for when the deliverable is due.
attestation boolean A boolean whether or not the advisor attests to "providing the agreed upon services to the client and the included evidence is accurate".
notes string If the template allows notes as evidence, these are the notes.
urls string list If the template allows URLs as evidence, this contains the list of URLs.
fileNames string list If the template allows files to be uploaded as evidence, this contains the list of file names.
allowedFileTypes string list The only file types that can be submitted on a deliverable. Valid file types are [".png",".jpg",".pdf",".docx"]
intervalType string This is the interval type specified in the template. Valid values are "days", "weeks", "months", and "years".
interval number This is the interval specified in the template.
trigger string This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".
advisor object The advisor on the deliverable.
client object The client on the deliverable.

List Deliverable Templates

Example Request

curl /api/public/v1/deliverable_templates \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

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

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

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "name":"My Template"
      "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},
      "esignTemplateExternalID":"ext123"
      "dueDateType":"calculate"
      "dueDateIntervalType":"years",
      "dueDateInterval":1,
      "dueDateTrigger":"invoice_paid"
      "recurring":true
      "recurringIntervalType":"years"
      "recurringInterval":1
      "recurringTrigger":"last_completed_deliverable"
      "maxRecurrence":2,
      "allowedFileTypes":[".png",".jpg",".pdf",".docx"]
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/deliverable_templates

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 deliverable templates sorted by created_at in descending order

Get a Deliverable Template

Example Request

curl /api/public/v1/deliverable_templates/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"My Template"
  "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},,
  "esignTemplateExternalID":"ext123"
  "dueDateType":"calculate"
  "dueDateIntervalType":"years",
  "dueDateInterval":1,
  "dueDateTrigger":"invoice_paid"
  "recurring":true
  "recurringIntervalType":"years"
  "recurringInterval":1
  "recurringTrigger":"last_completed_deliverable"
  "maxRecurrence":2,
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"]
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the deliverable template to fetch.

Response

Returns the requested deliverable template

Create a Deliverable Template

Example Request

curl /api/public/v1/deliverable_templates \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"name":"My Template", "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},, "intervalType":"years", "interval":1, "trigger":"invoice_paid", "allowedFileTypes":[".pdf",".png",".docx",".jpg"]}' \
     -X POST

import "net/http"

type createDeliverableTemplateReq struct {
  Name                  string
  DetailedEvidenceTypes map[string]interface{}
  DueDateType           string
  IntervalType          string
  Interval              uint
  Trigger               string
  AllowedFileTypes      []string
}

// Marshall request data to JSON string
data := createDeliverableTemplateReq{
  Name:                   "My Template",
  DetailedEvidenceTypes:  map[string]interface{}{"attestation":{"visible":true,"required":false}},
  DueDateType:            "calculate"
  DueDateIntervalType:    "years",
  DueDateInterval:        1,
  DueDateTrigger:         "invoice_paid",
  AllowedFileTypes:       [".pdf",".png",".docx",".jpg"],
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"My Template"
  "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},
  "esignTemplateExternalID":""
  "dueDateType":"calculate"
  "dueDateIntervalType":"years",
  "dueDateInterval":1,
  "dueDateTrigger":"invoice_paid",
  "recurring":false,
  "recurringIntervalType":"",
  "recurringInterval":0,
  "recurringTrigger":"",
  "maxRecurrence":0,
  "allowedFileTypes":[".pdf",".png",".docx",".jpg"]
}

Required Permissions

User must be Full-access Advisor or Admin.

HTTP Request

POST /api/public/v1/deliverable_templates

Arguments

Value Required Type Description
name true string The name of the template.
detailedEvidenceTypes true object The types of evidence that can be used for the template. Valid keys are "file", "url", "esign", "notes" and "attestation". Each has an object with 2 values visible and required. Visible determines whether or not they can see/submit that evidence type.
esignTemplateExternalID conditional string If "esign" is included in evidenceTypes, this field is required. The eSign template that will be used for evidence if "esign" is included in evidenceTypes.
dueDateType true string Valid values are "specify", "calculate".
dueDateIntervalType conditional string If dueDateType is set to "calculate", this field is required. This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
dueDateInterval conditional number If dueDateType is set to "calculate", this field is required. This is the interval specified in dueDateIntervalType units.
dueDateTrigger conditional string If dueDateType is set to "calculate", this field is required. This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".
recurring false boolean Recurring deliverables will automatically create a new deliverable when triggered and assign it to the same advisor.
recurringIntervalType conditional string If recurring is set to true, this field is required. This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
recurringInterval conditional number If recurring is set to true, this field is required. This is the interval specified in recurringIntervalType units.
recurringTrigger conditional string If recurring is set to true, this field is required. This is the trigger used to calculate when the deliverable is due. Valid value "last_completed_deliverable".
maxRecurrence false number Total number of deliverables owed.
allowedFileTypes false string list The only file types that can be submitted on a deliverable. Valid file types are [".png",".jpg",".pdf",".docx"]

Response

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

Update a Deliverable Template

Example Request

curl /api/public/v1/deliverable_templates/2 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"advisorID":1, "clientID":2, "triggerDate":1234567}' \
     -X PUT

import "net/http"

type updateDeliverableTemplateReq struct {
  Name          string
  DetailedEvidenceTypes map[string]interface{}
  DueDateIntervalType  string
  DueDateInterval      uint
  DueDateTrigger       string
  AllowedFileTypes     []string
}

// Marshall request data to JSON string
data := updateDeliverableTemplateReq{
  Name:          "My Template",
  DetailedEvidenceTypes:  map[string]interface{}{"attestation":{"visible":true,"required":false}},
  DueDateIntervalType:  "years",
  DueDateInterval:      1,
  DueDateTrigger:       "invoice_paid",
  AllowedFileTypes:     [".png",".jpg",".pdf",".docx"],
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "name":"My Template"
  "detailedEvidenceTypes":{"file":{"visible":true,"required":false}},
  "esignTemplateExternalID":""
  "dueDateType":"calculate"
  "dueDateIntervalType":"years",
  "dueDateInterval":1,
  "dueDateTrigger":"invoice_paid",
  "recurring":false,
  "recurringIntervalType":"",
  "recurringInterval":0,
  "recurringTrigger":"",
  "maxRecurrence":0,
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"]
}

Required Permissions

User must be Full-access Advisor or Admin.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the deliverable template to update.

Arguments

Value Required Type Description
name false string The name of the template.
detailedEvidenceTypes false object The types of evidence that can be used for the template. Valid keys are "file", "url", "esign", "notes" and "attestation". Each has an object with 2 values visible and required. Visible determines whether or not they can see/submit that evidence type.
esignTemplateExternalID conditional string If "esign" is included in evidenceTypes, this field is required. The eSign template that will be used for evidence if "esign" is included in evidenceTypes.
dueDateType true string Valid values are "specify", "calculate".
dueDateIntervalType conditional string If dueDateType is set to "calculate", this field is required. This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
dueDateInterval conditional number If dueDateType is set to "calculate", this field is required. This is the interval specified in dueDateIntervalType units.
dueDateTrigger conditional string If dueDateType is set to "calculate", this field is required. This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".
recurring false boolean Recurring deliverables will automatically create a new deliverable when triggered and assign it to the same advisor.
recurringIntervalType conditional string If recurring is set to true, this field is required. This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
recurringInterval conditional number If recurring is set to true, this field is required. This is the interval specified in recurringIntervalType units.
recurringTrigger conditional string If recurring is set to true, this field is required. This is the trigger used to calculate when the deliverable is due. Valid value "last_completed_deliverable".
maxRecurrence false number Total number of deliverables owed.
allowedFileTypes false string list The only file types that can be submitted on a deliverable. Valid file types are [".png",".jpg",".pdf",".docx"]

Response

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

List Deliverables

Example Request

curl /api/public/v1/deliverables?statuses[]=past_due&statuses[]=open \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables?statuses[]=past_due&statuses[]=open", nil)
// ...

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

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "advisorID":1,
      "clientID":2,
      "engagementID":3,
      "status":"open",
      "templateName":"My Template",
      "triggerDate":1234567,
      "dueDate":1234567,
      "attestation":false,
      "notes":"",
      "urls":[],
      "fileNames":[],
      "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
      "intervalType":"years",
      "interval":1,
      "trigger":"invoice_paid",
      "advisor":{},
      "client":{}
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/deliverables

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).
statuses empty string list This will only return deliverables with the specified statuses.
advisorIDs empty string list This will only return deliverables for the specified advisors.
clientIDs empty string list This will only return deliverables for the specified clients.
engagementID empty number This will only return deliverables with the specified engagement ID.
dueDateMin empty number This will only return deliverables with a minimum due date of the specified unix epoch.
dueDateMax empty number This will only return deliverables with a maximum due date of the specified unix epoch.
completedAfter empty number This is a unix timestamp to filter by completedAt.
completedBefore empty number This is a unix timestamp to filter by completedAt.
updatedAfter empty number This is a unix timestamp to filter by updatedAt.
updatedBefore empty number This is a unix timestamp to filter by updatedAt.

Response

Returns a list of deliverables sorted by created_at in descending order

Get a Deliverable

Example Request

curl /api/public/v1/deliverables/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":false,
  "notes":"",
  "urls":[],
  "fileNames":[],
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the deliverable to fetch.

Response

Returns the requested deliverable

Create a Deliverable

Example Request

curl /api/public/v1/deliverables \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"templateID":1, "advisorID":1, "clientID":2, "triggerDate":1234567}' \
     -X POST

import "net/http"

type createDeliverableReq struct {
  TemplateID         uint
  AdvisorID          uint
  ClientID           uint
  TriggerDate        uint64
}

// Marshall request data to JSON string
data := createDeliverableReq{
  TemplateID:  1
  AdvisorID:   1,
  ClientID:    2,
  TriggerDate: 1234567,
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":false,
  "notes":"",
  "urls":[],
  "fileNames":[],
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

Required Permissions

User must be Full-access Advisor or Admin.

HTTP Request

POST /api/public/v1/deliverables

Arguments

Value Required Type Description
templateID true number This is the ID of the template to use when creating the deliverable.
advisorID true number This will create the deliverable and advisor relationship.
clientID true number This will create the deliverable and client relationship.
triggerDate true number This is the unix timestamp used to calculate the date the deliverable is due.

Response

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

Update a Deliverable

Example Request

curl /api/public/v1/deliverables/2 \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"advisorID":1, "clientID":2, "triggerDate":1234567}' \
     -X PUT

import "net/http"

type updateDeliverableReq struct {
  AdvisorID   uint
  ClientID    uint
  TriggerDate uint64
}

// Marshall request data to JSON string
data := updateDeliverableReq{
  AdvisorID:   3,
  ClientID:    4,
  TriggerDate: 12345678,
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":false,
  "notes":"",
  "urls":[],
  "fileNames":[],
  "allowedFileTypes":[".pdf"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

Required Permissions

User must be Full-access Advisor or Admin.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the deliverable to update.

Arguments

Value Required Type Description
advisorID false number This will create the deliverable and advisor relationship. If this is not sent on the request, the existing advisor ID will be maintained.
clientID false number This will create the deliverable and client relationship. If this is not sent on the request, the existing client ID will be maintained.
triggerDate false number This is the unix timestamp used to calculate the date the deliverable is due. If this is not sent on the request, the existing trigger date will be maintained.

Response

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

Submit a Deliverable

Example Request

curl /api/public/v1/deliverables/2/submit \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"description":"My description", "attestation":true, "notes":"My notes", "url":"https://www.advicepay.com", "fileNames":["file1.pdf","file2.pdf"]}' \
     -X PUT

import "net/http"

type submitDeliverableReq struct {
  Description string
  Attestation boolean
  Notes       string
  URL         string
  FileNames   []string
}

// Marshall request data to JSON string
data := submitDeliverableReq{
  Description:  "My description",
  Attestation:  true,
  Notes:        "My notes",
  URL:          "https://www.advicepay.com",
  FileNames:    []string{"file1.pdf", "file2.pdf"}
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "engagementID":3,
  "status":"complete",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "notes":"My notes",
  "attestation":true,
  "urls":["https://www.advicepay.com"],
  "fileNames":["file1.pdf", "file2.pdf"],
  "allowedFileTypes":[".png",".jpg",".pdf",".docx"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid",
  "advisor":{},
  "client":{}
}

Required Permissions

User must be an Advisor or Admin.

HTTP Request

PUT /api/public/v1/deliverables/<ID>/submit

URL Parameters

Parameter Description
ID The ID of the deliverable to submit.

Arguments

Value Required Type Description
description false string This is the advisor-defined description of the deliverable. It should fill in any details missing from the title.
attestation false boolean A boolean whether or not the advisor attests to "providing the agreed upon services to the client and the included evidence is accurate".
notes false string These are the notes from the advisor.
url false string This is the URL of the evidence provided by the advisor.
fileNames false string list This is the collection of file names containing the evidence uploaded by the advisor.

Response

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

Get the File Upload URL

AdvicePay uses pre-signed upload URLs that are only good for 5 minutes.

Example Request

curl /api/public/v1/deliverables/2/upload_url?fileName=myfile.pdf \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables/1/upload_url?fileName=myfile.pdf", nil)
// ...

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

Example Response

{
  "uploadURL": "https://ap.s3.amazonaws.com/thepath/myfile.pdf"
}

Required Permissions

User must be an Advisor or Admin.

HTTP Request

GET /api/public/v1/deliverables/<ID>/upload_url

URL Parameters

Parameter Description
ID The ID of the deliverable to submit.

Arguments

Value Required Type Description
fileName true string This is the name of the file to be uploaded

Response

An object containing the upload URL, if the call succeeded. If the request failed, this call returns an error.

Deliverable File Download

Example Request

curl /api/public/v1/deliverables/1/files/my%20file.pdf/download \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables/1/files/my%20file.pdf/download?expect=json", nil)
// ...

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

Example Response

{
  "data":"Base64-encoded Data Here",
}

Required Permissions

User must be an Advisor or Admin.

HTTP Request

GET /api/public/v1/deliverables/<ID>/files/<fileName>/download

URL Parameters

Parameter Description
ID The ID of the deliverable to submit.
fileName The URL-encoded name of the file to be downloaded

Query Parameters

Parameter Default Type Description
expect binary string The expected response type. Must be one of "binary" (default) or "json".

Response

Returns the requested file. If "expect" query parameter is "binary" or omitted, the response will contain the binary representation of the file. The response header will have a "Content-Type" of "application/octet-stream" and "Content-Transfer-Encoding" of "binary". If "expect" query parameter is "json", the response will contain a file transfer object with a Base64-encoded representation of the file.

Get the File Download URL (deprecated in favor of deliverable file download)

AdvicePay uses pre-signed download URLs that are only good for 5 minutes.

Example Request

curl /api/public/v1/deliverables/2/download_url?fileName=myfile.pdf \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/deliverables/1/download_url?fileName=myfile.pdf", nil)
// ...

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

Example Response

{
  "downloadURL": "https://ap.s3.amazonaws.com/thepath/myfile.pdf"
}

Required Permissions

User must be an Advisor or Admin.

HTTP Request

GET /api/public/v1/deliverables/<ID>/download_url

URL Parameters

Parameter Description
ID The ID of the deliverable to submit.

Arguments

Value Required Type Description
fileName true string This is the name of the file to be downloaded

Response

An object containing the download URL, if the call succeeded. If the request failed, this call returns an error.

Engagements

The Engagement Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "externalID":"xyz123",
  "name":"Ongoing Engagement",
  "totalEngagementFee":2000,
  "advisor":{},
  "client":{},
  "agreements":[{}],
  "deliverables":[{}],
  "invoices":[{}],
  "subscriptions":[{}],
}

Attributes

Value Type Description
id number This is the engagement's unique indentifier, and should be stored to do any future queries for data belonging to that engagement.
createdAt number This is the unix timestamp for when the engagement was created.
updatedAt number This is the unix timestamp for when the engagement was updated.
deletedAt number This is the unix timestamp for when the engagement was deleted.
advisorID number This is the unique identifier of the advisor that the engagement was assigned to.
clientID number This is the unique identifier of the client that the engagement is associated with.
externalID string This is the external identifier for the engagement.
name string This is the name of the engagement.
totalEngagementFee number This is the total engagement fee (in cents) that is specified by an advisor when the chosen engagement workflow requires it.
advisor object The advisor on the engagement.
client object The client on the engagement.
agreements object list The agreements associated with the engagement (only visible in details view).
deliverables object list The deliverables associated with the engagement (only visible in details view).
invoices object list The invoices associated with the engagement (only visible in details view).
subscriptions object list The subscriptions associated with the engagement (only visible in details view).

The Engagement Revenue Object

{
  "engagementID":1,
  "projectedRevenue":1100,
  "totalEngagementFee":2000,
  "totalRevenue":100,
}

Attributes

Value Type Description
engagementID number This is the engagement's unique indentifier.
projectedRevenue number This is the revenue (in cents) that is projected to be collected in the future for the engagement.
totalEngagementFee number This is the total engagement fee (in cents) that is specified by an advisor when the chosen engagement workflow requires it.
totalRevenue number This is total revenue (in cents) that has already been collected for the engagement.

The Engagement Summary Object

{
  "id": 1,
  "createdAt": 1699922316,
  "updatedAt": 1701729256,
  "deletedAt": null,
  "advisorEmail": "example1@advicepay.com",
  "advisorExternalID": "Your_Advisor_External_ID",
  "advisorID": 1,
  "advisorName": "Bob Smith",
  "agreementIDs": [],
  "clientEmail": "example2@advicepay.com",
  "clientExternalID": "Your_Client_External_ID",
  "clientID": 2,
  "clientMetadata": {
    "My Dropdown": "Option 1"
  },
  "clientName": "Jim Jones",
  "deliverableIDs": [],
  "externalID": "",
  "invoiceIDs": [
      1,
      2,
  ],
  "name": "Standard Engagement",
  "officeID": 1,
  "primaryAgreementCreatedAt": 1699922316, 
  "primaryAgreementID": 1,
  "primaryAgreementName": "Financial Planning Agreement",
  "primaryAgreementStatus": "agreement_status_complete",
  "projectedRevenue": 120000,
  "subscriptionIDs": [
      1
  ],
  "totalEngagementFee": 150000,
  "totalRevenue": 40000
}

Attributes

Value Type Description
id number This is the engagement's unique indentifier.
createdAt number This is the unix timestamp for when the engagement was created.
updatedAt number This is the unix timestamp for when the engagement or any of the resources it contains were updated.
deletedAt number This is the unix timestamp for when the engagement was deleted.
advisorEmail string This is the advisor's email address.
advisorExternalID string This is the external ID of the advisor.
advisorID number This is the AdvicePay ID of the advisor.
advisorName number This is the full name of the advisor.
agreementIDs number list This is the list of IDs for all agreements on the engagement.
clientEmail string This is the client's email address.
clientExternalID string This is the external ID of the client.
clientID string This is the AdvicePay ID of the client.
clientMetadata object Any additonal information added to the client via a custom attribute will show here.
clientName string This is the full name of the client.
deliverableIDs number list This is the list of IDs for all deliverables on the engagement.
externalID number This is the external identifier for the engagement.
invoiceIDs number list This is the list of IDs of the invoices on the engagement.
name string This is the name of the engagement.
officeID number This is the ID of the engagement's office.
primaryAgreementCreatedAt number This is the unix timestamp for when the primary agreement was created.
primaryAgreementID number This is the ID of the primary agreement on the engagement.
primaryAgreementName string This is the name of the template used to create the primary agreement.
primaryAgreementStatus string This is the status of the primary agreement. It will be one of: "agreement_status_created" (no action has been taken), "agreement_status_opened" (a signer has opened the document), "agreement_status_complete" (all signers have signed the document), "agreement_status_voided" (the signature request has been canceled), "agreement_status_draft" (the signature request needs to be completed before sending)
projectedRevenue number This is the revenue (in cents) that is projected to be collected in the future for the engagement.
subscriptionIDs number list This is the list of IDs of the subscriptions on the engagement.
totalEngagementFee number This is the total engagement fee (in cents) that is specified by an advisor when the chosen engagement workflow requires it.
totalRevenue number This is total revenue (in cents) that has already been collected for the engagement.

List Engagements

Example Request

curl /api/public/v1/engagements?externalIDs[]=xyz123 \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

// Build request
req, err := http.NewRequest("GET", "/api/public/v1/engagements?externalIDs[]=xyz123", nil)
// ...

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

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "advisorID":1,
      "clientID":2,
      "externalID":"xyz123",
      "name":"Ongoing Engagement",
      "advisor":{},
      "client":{},
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/engagements

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).
externalIDs empty string list This will only return engagements with the specified external IDs.
advisorIDs empty string list This will only return engagements for the specified advisors.
clientIDs empty string list This will only return engagements for the specified clients.
createdAfter empty number This is a unix timestamp to filter by createdAt.
createdBefore empty number This is a unix timestamp to filter by createdAt.

Response

Returns a list of engagements sorted by created_at in descending order

Get an Engagement

Example Request

curl /api/public/v1/engagements/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "clientID":2,
  "externalID":"xyz123",
  "name":"Ongoing Engagement",
  "advisor":{},
  "client":{},
  "agreements":[{}],
  "deliverables":[{}],
  "invoices":[{}],
  "subscriptions":[{}],
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the engagement to fetch.

Response

Returns the requested engagement

Get Revenue for an Engagement

Example Request

curl /api/public/v1/engagements/1/revenue \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "engagementID":1,
  "projectedRevenue":1100,
  "totalRevenue":100
}

HTTP Request

GET /api/public/v1/engagements/<ID>/revenue

URL Parameters

Parameter Description
ID The ID of the engagement whose revenue to calculate.

Response

Returns the requested revenue for the engagement

Get Engagement Summaries

Example Request

curl /api/public/v1/engagements/summary \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

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

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

Example Response

{
  "items": [
    {
      "id": 1,
      "createdAt": 1699922316,
      "updatedAt": 1701729256,
      "deletedAt": null,
      "advisorEmail": "example1@advicepay.com",
      "advisorExternalID": "Your_Advisor_External_ID",
      "advisorID": 1,
      "advisorName": "Bob Smith",
      "agreementIDs": [],
      "clientEmail": "example2@advicepay.com",
      "clientExternalID": "Your_Client_External_ID",
      "clientID": 2,
      "clientMetadata": {
        "My Dropdown": "Option 1"
      },
      "clientName": "Jim Jones",
      "deliverableIDs": [],
      "externalID": "",
      "invoiceIDs": [
          1,
          2,
      ],
      "name": "Standard Engagement",
      "officeID": 1,
      "primaryAgreementCreatedAt": 1699922316,
      "primaryAgreementID": 1,
      "primaryAgreementName": "Financial Planning Agreement",
      "primaryAgreementStatus": "agreement_status_complete",
      "projectedRevenue": 120000,
      "subscriptionIDs": [
          1
      ],
      "totalEngagementFee": 150000,
      "totalRevenue": 40000
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/engagements/summary

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).
externalIDs empty string list This will only return summaries for engagements with the specified external IDs.
advisorIDs empty string list This will only return summaries for engagements for the specified advisors.
clientIDs empty string list This will only return summaries for engagements for the specified clients.
createdAfter empty number This is a unix timestamp to filter by the time the engagement was created.
createdBefore empty number This is a unix timestamp to filter by the time the engagement was created.
updatedAfter empty number This is a unix timestamp to filter by the time the engagement or any of its contained resources were last updated.

Response

Returns a list of engagement summaries sorted by created_at in descending order

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", "Semi-Annual recurring", or "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".

Invoices

The Invoice Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "clientID":1,
  "advisorID":2,
  "engagementID": 3,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":1551201267,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "acceptedPaymentMethods":["ach","ccd","check"],
  "refundAmount":0,
  "refundDate":0,
  "status":"paid",
  "splitRepCode":"HN15448",
  "advisor": {},
  "client": {},
  "serviceDescriptions": [],
  "payURL": "",
}

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 in AdvicePay.
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.
engagementID number This is the ID of the engagement 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 the first description in the list of descriptions on the invoice that the advisor provided. Deprecated. Please see the serviceDescriptions attribute.
invoiceDate number This is the date in unix time that the invoice was sent to the client (set to 0 for upcoming invoices).
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", "Semi-Annual recurring", or "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.
acceptedPaymentMethods string list These are the accepted payment method types. These can be any combination of "ach", "ccd", "check", or left empty to indicate payment outside of AdvicePay
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. This will be populated if the firm setting for split rep codes is set to Standard
advancedSplitRepCodes object list The list of advanced split rep codes. This will be populated if the firm setting for split rep coes is set to Advanced
advisor object The advisor on the invoice.
client object The client on the invoice.
serviceDescriptions object list The service descriptions on the invoice.
payURL string The URL were the invoice can be paid.

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":0,
      "clientID":1,
      "advisorID":2,
      "engagementID": 3,
      "subscriptionID":1,
      "amount":1000,
      "description":"description",
      "invoiceDate":1551201267,
      "dueDate":1551201267,
      "failedAt":1551201267,
      "frequency":"Monthly recurring",
      "number":1001,
      "paidDate":1551201267,
      "acceptedPaymentMethods":["ach","ccd","check"],
      "refundAmount":0,
      "refundDate":0,
      "status":"paid",
      "splitRepCode":"HN15448",
      "advisor": {},
      "client": {},
      "payURL": "",
    },
    ...
  ],
  "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", "Semi-Annual recurring", or "Annual recurring".
paidAfter empty number This is a unix timestamp to filter by paidDate.
paidBefore 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.
engagementID empty number Filter by invoice engagement.
updatedAfter empty number This is a unix timestamp to filter by updatedAt.
updatedBefore empty number This is a unix timestamp to filter by updatedAt.

Response

Returns a list of invoices sorted by created_at in descending order

Get an Invoice

Example Request

curl /api/public/v1/invoices/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "clientID":1,
  "advisorID":2,
  "engagementID": 3,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":1551201267,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "acceptedPaymentMethods":["ach","ccd","check"],
  "refundAmount":0,
  "refundDate":0,
  "status":"paid",
  "splitRepCode":"",
  "advancedSplitRepCodes":[
    {
        "id":123,
        "createdAt":123456,
        "updatedAt":123456,
        "deletedAt":0,
        "advisorID":2,
        "percent":100,
        "advisor":{}
    }
  ]
  "advisor": {},
  "client": {},
  "payURL": "",
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the invoice to fetch.

Response

Returns the requested invoice

Create an Invoice

Example Request

curl /api/public/v1/invoices \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"amount":1000, "dueDate":1551201267, "clientID":1, "serviceDescriptions":[{"title":"service one", "text":"description"}]}' \
     -X POST

import "net/http"

type serviceDescription struct {
  Title string
  Text  string
}

type createInvoiceReq struct {
  Amount              int
  DueDate             int64
  ClientID            uint
  ServiceDescriptions []serviceDescriptionsReq
}


// Marshall request data to JSON string
data := createInvoiceReq{
  Amount:              1000,
  DueDate:             1551201267,
  ClientID:            1,
  ServiceDescriptions: []serviceDescription{
    {Title: "service one", Text:"description"},
  },
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "clientID":1,
  "advisorID":2,
  "engagementID": 3,
  "subscriptionID":0,
  "amount":1000,
  "description":"description",
  "dueDate":1551201267,
  "failedAt":0,
  "frequency":"Single Payment",
  "number":1001,
  "paidDate":0,
  "acceptedPaymentMethods":["ach","ccd","check"],
  "refundAmount":0,
  "refundDate":0,
  "status":"unpaid",
  "splitRepCode":"",
  "advisor": {},
  "client": {},
  "payURL": "",
}

Required Permissions

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

HTTP Request

POST /api/public/v1/invoices

Arguments

Value Required Type Description
amount true number Number in cents, value must be greater than 50.
dueDate true number This is due date in unix time. Must be a date in the future.
clientID true number This is the AdvicePay ID of the client for which the invoice is intended.
serviceDescriptions true string A list of service descriptions that will be displayed on the invoice.
advanceBilling false boolean Default is false and will bill in arrears. If set to true, will bill in advance.
externalEngagementID false string Creating an invoice will create a new engagement. The engagement's external ID will be set to this value upon creation.
sendAsEmail false boolean Default is false. If set to true, email with payment link will be sent to client.
emailMessage false string Custom message to be included in the email sent to client.
acceptedPaymentMethods false string list Default is ["ach","ccd"]. This is the payment options for the invoice. Must be an string list combination of "ach", "ccd", or "check.

Response

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

Download an Invoice PDF

Example Request

curl -O -J /api/public/v1/invoices/1/download?expect=json \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "data":"Base64-encoded Data Here",
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the invoice to download.

Query Parameters

Parameter Default Type Description
expect binary string The expected response type. Must be one of "binary" (default) or "json".

Response

Returns a PDF file for the invoice. If "expect" query parameter is "binary" or omitted, the response will contain the binary representation of the file. The response header will have a "Content-Type" of "application/octet-stream" and "Content-Transfer-Encoding" of "binary". If "expect" query parameter is "json", the response will contain a file transfer object with a Base64-encoded representation of the file.

Refund an Invoice

Example Request

curl /api/public/v1/invoices/1/refund \
     -H "Authorization: Bearer <advicepay_api_key>" \
     -H "Content-Type: application/json" \
     -d '{"amount":"100000","customMessage":"Your refund is on the way"}'
     -X PUT

import (
  "net/http"
  "encoding/json"
)

// Build request
d := struct{
    Amount string `json:"amount"`
    CustomMessage string `json:"customMessage"`
}{
  Amount: 10000,
  CustomMessage:"Your refund is on the way",
}
jsonData, err := json.Marshal(d)
// ...
req, err := http.NewRequest("PUT", "/api/public/v1/invoices/1/refund", bytes.NewBuffer(jsonData))
req.Header.Add("Authorization", "Bearer <advicepay_api_key>")
req.Header.Add("Content-Type", "application/json")
// ...

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "clientID":1,
  "advisorID":2,
  "engagementID": 3,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":0,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "acceptedPaymentMethods":["ach","ccd","check"]
  "refundAmount":0,
  "refundDate":1671201267,
  "status":"refunded",
  "splitRepCode":"",
  "advancedSplitRepCodes":[
    {
        "id":123,
        "createdAt":123456,
        "updatedAt":123456,
        "deletedAt":0,
        "advisorID":2,
        "percent":100,
        "advisor":{}
    }
  ]
  "advisor": {},
  "client": {},
  "serviceDescriptions": [],
  "payURL": "",
}

HTTP Request

PUT /api/public/v1/invoices/<ID>/refund

URL Parameters

Parameter Description
ID The ID of the invoice to refund.

Arguments

Value Required Type Description
amount true number Number in cents to refund, value must be greater than 50 and less than or equal to the invoice amount paid.
customMessage false string If included, this will be included in the email notifying the client of the refund.

Response

Returns the refunded invoice

Notifications

The Notification Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "advisorID":1,
  "amount":0,
  "clientID":1,
  "invoiceID":1,
  "subscriptionID":0,
  "key":"invoice-failed",
  "text":"Invoice #1234 of $1.00 failed",
}

Attributes

Value Type Description
id number This is the notification's unique indentifier, and should be stored to do any future queries for data belonging to that notification.
createdAt number This is the unix timestamp for when the notification was created.
updatedAt number This is the unix timestamp for when the notification was updated.
deletedAt number This is the unix timestamp for when the notification was deleted.
advisorID number This is ID of the advisor that the notification belongs to.
amount number The amount (in cents) related to the notification (for money transfer notifications).
clientID number This is the ID of the client that the notification belongs to.
invoiceID number This is ID of the invoice associated with the notification (for invoice-specific notifications).
subscriptionID number This is the ID of the subscription associated with the notification (for subscription-specific notifications).
key string This is the key representing the type of the notification.
text string This is the text of the notification.

List Notifications

Example Request

curl /api/public/v1/notifications \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

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

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

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":0,
      "advisorID":1,
      "amount":0,
      "clientID":1,
      "invoiceID":1,
      "subscriptionID":0,
      "key":"invoice-failed",
      "text":"Invoice #1234 of $1.00 failed",
    },
    ...
  ],
  "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/notifications

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 notification advisor.
clientID empty number Filter by notification client.
createdAfter empty number This is a unix timestamp to filter by createdAt.
createdBefore empty number This is a unix timestamp to filter by createdAt.

Response

Returns a list of notifications sorted by created_at in descending order

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":0,
  "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.

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":0,
      "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

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":0,
  "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":0,
  "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":0,
  "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>

URL Parameters

Parameter Description
ID The ID of the office to update.

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.

Other Objects

The Signer Object

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

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. [DEPRECATED]
completedAt number This is a unix timestamp for when the signer has completed the agreement.
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.
externalID string This is the identifier from your system in the AdvicePay database. It will be an empty string "" if there is no externalID under the corresponding client or advisor object.

The eSign Template Object

{
    "name": "ExampleTemplate",
    "description": "Example eSign Template"
}

Attributes

Value Type Description
name string This is the name of the template.
description string This is the template's description.

The Service Description Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":0,
  "invoiceID": 1,
  "title": "Monthly FP",
  "text": "Monthly financial planning services"
}

Attributes

Value Type Description
id number This is the service description's unique indentifier.
createdAt number This is the unix timestamp for when the service description was created.
updatedAt number This is the unix timestamp for when the service description was updated.
deletedAt number This is the unix timestamp for when the service description was deleted.
invoiceID number This is the ID of the invoice associated with the service description.
title string This is the short name to be displayed on the AdvicePay UI.
text string This is the text to be displayed on the invoice.

Create Service Description

Attributes

Value Required Type Description
title true string This is the short name to be displayed on the AdvicePay UI.
text true string This is the text to be displayed on the invoice.

The Advanced Split Rep Code Object

{
  "advisorID": 108,
  "advisorExternalID": "abc123",
  "firstName": "Bob",
  "lastName": "Smith",
  "splitPercent": 100,
  "My custom attribute 1": "My custom attribute 1 value",
  "My custom attribute 2": "My custom attribute 2 value"
}

Attributes

Value Type Description
advisorID number This is the ID of the advisor associated with the advanced split rep code.
advisorExternalID string This is used to specify an identifier from your system in the AdvicePay database.
firstName string The advisor's first name
lastName string The advisor's last name
splitPercent number The percentage of the commission to be paid to the advisor.
metadata string or string array Any additonal advisor attributes selected to be displayed under advanced repcode settings.

The One Time Payment Invoice Object

Create One Time Payment Invoice

Attributes

Value Required Type Description
amount true number Number in cents, value must be greater than 50.
dueDate true number This is due date in unix time. Must be a date in the future.
serviceDescriptions true object list A list of service descriptions that will be displayed on the invoices.

The File Transfer Object

{
  "data":"Base64-encoded data here",
}

Attributes

Value Type Description
data string This Base64-encoded representation of a file

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.

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. AdvicePay will provide you with the source once we have you set up in our system.

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.

Deep Linking

Many organizations require the ability to deep link into AdvicePay and this can be accomplished using the SSO RelayState. Deep linking is supported on any page within AdvicePay simply by setting the RelayState to /desiredPage. Below are some common examples.

RelayState

/clients/<ID>

RelayState

/payments/create

Optional Query Parameters

Parameter Description
userID This is the internal AdvicePay ID of the client to preselect.
externalUserID This is the external ID that you have defined on the client to preselect.
externalEngagementID The ID that you want to be populated on the engagement created by this payment request.
templateID The AdvicePay ID of the eSign template to preselect.
splitRepCode The split rep code to prepopulate. (not available if Advanced Split Rep Code is enabled in firm settings)

Subscriptions

The Subscription Object

{
  "id": 1,
  "createdAt": 1603399833,
  "updatedAt": 1603399833,
  "deletedAt": 0,
  "clientID": 2,
  "advisorID": 1,
  "engagementID": 3,
  "amount": 10000,
  "billingPeriods": 12,
  "frequency": "Monthly recurring",
  "dueDate": 1603951200,
  "status": "inactive",
  "resumeDate": 0,
  "billDate": 1603951200,
  "advisor": {},
  "client": {}
}

Attributes

Value Type Description
id number This is the subscription's unique indentifier.
createdAt number This is the unix timestamp for when the subscription was created in AdvicePay.
updatedAt number This is the unix timestamp for when the subscription was updated.
deletedAt number This is the unix timestamp for when the subscription was deleted.
clientID number This is the ID of the client that the subscription belongs to.
advisorID number This is ID of the advisor that the subscription belongs to.
engagementID number This is the ID of the engagement that the subscription belongs to.
amount number This is amount of the subscription in cents.
billingPeriods number This is the number of billing periods the subscription will bill.
billDate number This is the next date this subscription will be billed.
dueDate number This is due date in unix time for the subscription set by the advisor.
frequency string This is frequency of the subscription. It will be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", or "Annual recurring"
resumeDate number This is the date billing will resume if it has been paused.
status string This is status of the subscription. It will be one of: "inactive" (no action has been taken), "canceled" (subscription has been canceled), "active" (subscription has been activated), "deleted_by_stripe", "paused", "completed" (subscriptions has completed all billing periods), "pending_approval", "approval_rejected".
advisor object The advisor on the subscription.
client object The client on the subscription.

List Subscriptions

Example Request

curl /api/public/v1/subscriptions \
     -H "Authorization: Bearer advicepay_api_key" \

import "net/http"

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

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

Example Response

{
  "items": [
    {
      "id": 1,
      "createdAt": 1603399833,
      "updatedAt": 1603399833,
      "deletedAt": 0,
      "clientID": 2,
      "advisorID": 1,
      "engagementID": 3,
      "amount": 10000,
      "billingPeriods": 12,
      "frequency": "Monthly recurring",
      "dueDate": 1603951200,
      "billDate": 1603951200,
      "resumeDate": 0,
      "status": "inactive",
      "advisor": {},
      "client": {}
    }
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/subscriptions

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 subscription status. Must be one of: "inactive", "canceled", "active", "deleted_by_stripe", "paused", "completed", "pending_approval", "approval_rejected".
frequency empty string Filter by subscription frequency. Must be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", "Annual recurring".
advisorID empty number Filter by subscription advisor.
clientID empty number Filter by subscription client.
engagementID empty number Filter by subscription engagement.

Response

Returns a list of subscriptions sorted by created_at in descending order

Get a Subscription

Example Request

curl /api/public/v1/subscriptions/1 \
     -H "Authorization: Bearer advicepay_api_key"

import "net/http"

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

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

Example Response

{
  "id": 1,
  "createdAt": 1603399833,
  "updatedAt": 1603399833,
  "deletedAt": 0,
  "clientID": 2,
  "advisorID": 1,
  "engagementID": 3,
  "amount": 10000,
  "billingPeriods": 12,
  "frequency": "Monthly recurring",
  "dueDate": 1603951200,
  "billDate": 1603951200,
  "resumeDate": 0,
  "status": "inactive",
  "advisor": {},
  "client": {}
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the subscription to fetch.

Response

Returns the requested subscription

Create a Subscription

Example Request

curl /api/public/v1/subscriptions \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"amount":1000, "dueDate":1551201267, "clientID":1, "frequency":"Monthly recurring", "serviceDescriptions":[{"title":"service one", "text":"description"}]}' \
     -X POST

import "net/http"

type serviceDescription struct {
  Title string
  Text  string
}

type createSubscriptionReq struct {
  Amount              int
  DueDate             int64
  ClientID            uint
  Frequency           string 
  ServiceDescriptions []serviceDescriptionsReq
}


// Marshall request data to JSON string
data := createSubscriptionReq{
    Amount:              1000,
  DueDate:             1551201267,
  ClientID:            1,
  Frequency            "Monthly recurring", 
  ServiceDescriptions: []serviceDescription{
    {Title: "service one", Text:"description"},
  },
}
jsonData, err := json.Marshal(data)
// ...

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

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

Example Response

{
  "id": 1,
  "createdAt": 1551201267,
  "updatedAt": 1551201267,
  "deletedAt": 0,
  "clientID": 1,
  "advisorID": 2,
  "engagementID": 3,
  "amount": 1000,
  "frequency": "Monthly recurring",
  "dueDate": 1551201267,
  "status": "inactive",
  "resumeDate": 0,
  "billDate": 1551201267,
  "advisor": {},
  "client": {}
}

Required Permissions

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

HTTP Request

POST /api/public/v1/subscriptions

Arguments

Value Required Type Description
amount true number Number in cents, value must be greater than 50.
dueDate true number This is due date in unix time. Must be a date in the future.
clientID true number This is the AdvicePay ID of the client for which the subscription is intended.
frequency true string Subscription frequency. Must be one of: "Single Payment", "Monthly recurring", "Quarterly recurring", "Semi-Annual recurring", "Annual recurring".
serviceDescriptions true object list A list of service descriptions that will be displayed on the invoices.
advanceBilling false boolean Default is false and will bill in arrears. If set to true, will bill in advance.
sendAsEmail false boolean Default is false. If set to true, email with payment link will be sent to client.
emailMessage false string Custom message to be included in the email sent to client.
acceptedPaymentMethods false string list Default is ["ach","ccd"]. This is the payment options for the subscription. Must be an string list combination of "ach", "ccd", or "check.
billingPeriods false number Sets the max billing periods the subscriptions will bill.
otpInvoice false object An upfront one time payment to be charged when activating the subscription.

Response

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

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 accordingly. We highly recommend using the arrivalBefore and arrivalAfter parameters to limit the size of the responses.

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": "extIDa",
      "advisorID": 1,
      "agreementID": 1,
      "invoiceID": 1,
      "invoiceNum": 1001,
      "invoiceType": "Single Payment",
      "recurringStartDate": 0,
      "recurringEndDate": 0,
      "invoiceDescription": "first description",
      "serviceDescriptions": ["first description", "second description"],
      "splitRepCode": "",
      "advancedSplitRepCodes": [
        {
          "advisorExternalID": "extIDa",
          "advisorID": 1,
          "firstName": "first",
          "lastName": "last",
          "splitPercent": 50
        },
        {
          "advisorExternalID": "extIDb",
          "advisorID": 2,
          "firstName": "adv2first",
          "lastName": "adv2last",
          "splitPercent": 50
        }
      ],
    }
  ]
}

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 arrival 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", "check"
paymentType string This is the type of payment used for the transaction. It will be either "CC" (credit card), "ACH" (bank account), or "CHK" (check)
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.
paymentMessage string This is the note that was written when the invoice was marked as paid.
clientName string This is the first and last name of the client.
clientExternalID string This is the optional id field 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 field on the advisor object.
advisorID number This is AdvicePay's unique internal advisor ID.
agreementID number This is AdvicePay's unique internal agreement ID.
engagementExternalID string This is the optional id field on the engagement object.
engagementID number This is AdvicePay's unique internal engagement ID.
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", or "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 first description on the invoice (Deprecated in favor of serviceDescriptions attribute).
serviceDescriptions string list This is the array of descriptions on the invoice.
splitRepCode string This is split/rep code for the invoice that the advisor provided. This will be populated if the firm setting for split rep codes is set to Standard.
advancedSplitRepCodes object list The list of advanced split rep codes. This will be populated if the firm setting for split rep coes is set to Advanced.

List Transfers

Required Permissions

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

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?arrivalAfter=1551201266&perPage=5", 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,
          "paymentMessage": "example message",
          "clientName": "first last",
          "clientExternalID": "",
          "advisorName": "first last",
          "advisorEmail": "example@advicepay.com",
          "advisorExternalID": "extIDa",
          "advisorID": 1,
          "agreementID": 1,
          "engagementID": 3,
          "engagementExternalID": "ABC123",
          "invoiceID": 1,
          "invoiceNum": 1001,
          "invoiceType": "Single Payment",
          "recurringStartDate": 0,
          "recurringEndDate": 0,
          "invoiceDescription": "first description",
          "serviceDescriptions": ["first description", "second description"],
          "splitRepCode": "",
          "advancedSplitRepCodes": [
            {
              "advisorExternalID": "extIDa",
              "advisorID": 1,
              "firstName": "first",
              "lastName": "last",
              "splitPercent": 50
            },
            {
              "advisorExternalID": "extIDb",
              "advisorID": 2,
              "firstName": "adv2first",
              "lastName": "adv2last",
              "splitPercent": 50
            }
          ]
        }
      ]
    },
    ...
  ],
  "perPage": 5,
  "hasMore": true
}

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

shell go