NAV Navbar
shell go

Introduction

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

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

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

Authorization

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 might be under different accounts, as well as 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. 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

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 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 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)
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 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

Authentication

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":null,
  "email":"example@advicepay.com",
  "parentID":32,
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "parentRoleTitle":"Firm Manager",
  "accountOwner":false,
}

HTTP Request

GET /api/public/v1/me

Response

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

Offices

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

The Office Object

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

Attributes

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

Get an Office

Example Request

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

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

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

Example Response

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

Required Permissions

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the office to fetch.

Response

Returns the requested office

Create an Office

Example Request

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

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

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

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

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

Example Response

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

Required Permissions

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

HTTP Request

POST /api/public/v1/offices

Arguments

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

Response

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

Update an Office

Example Request

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

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

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

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

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

Example Response

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

Required Permissions

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

HTTP Request

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

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.

List Offices

Example Request

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

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

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

Example Response

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

Required Permissions

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

HTTP Request

GET /api/public/v1/offices

Query Parameters

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

Response

Returns a list of offices sorted by created_at in descending order

Admins

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

The Admin Object

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

Attributes

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

Create an Admin

Example Request

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

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

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

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

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

Example Response

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

Required Permissions

User must be Managing Advisor, 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 for uniqueness in our database.
firstName true string Trailing or leading whitespaces will be trimmed.
lastName true string Trailing or leading whitespaces will be trimmed.
permission true string Must be one of the following: "Admin", "Analyst". "Admin" gives the same access and functionality as the parent user. "Analyst" gives read-only access to the parent user's account.
parentID true number The unique ID of the advisor whose account the admin will associated with. 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.

Advisors

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

The Advisor Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "externalID":"abc123",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "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.

Get an Advisor

Example Request

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

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

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

Example Response

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "email":"example@advicepay.com",
  "firstName":"first",
  "lastName":"last",
  "verified":true,
  "roleTitle":"Advisor",
  "completedOnboarding":true,
  "officeID":1,
  "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":null,
  "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.
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 '{"firstName":"first", "lastName":"last", "permission":"Advisor", "externalID": "abc123", "officeID": 1}' \
     -X PUT
import "net/http"

type updateAdvisorReq struct {
    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{
  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":null,
  "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
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

List Advisors

Example Request

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

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

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

Example Response

{
  "items": [
    {
      "id":1,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":null,
      "email":"example@advicepay.com",
      "externalID":"abc123",
      "firstName":"first",
      "lastName":"last",
      "verified":true,
      "roleTitle":"Advisor",
      "completedOnboarding":true,
      "officeID":1,
      "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

Clients

The Client Object

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

Attributes

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

Get a Client

Example Request

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

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

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

Example Response

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the client to fetch.

Response

Returns the requested client

Create a Client

Essential accounts are limited to 10 Clients.

Example Request

curl /api/public/v1/clients \
     -H "Authorization: Bearer advicepay_api_key" \
     -d '{"email":"example@advicepay.com", "firstName":"first", "lastName":"last", "advisorID":1, "externalID": "abc123", "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":null,
  "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"]}
}

Required Permissions

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

HTTP Request

POST /api/public/v1/clients

Arguments

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

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 true 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 true string Trailing or leading whitespaces will be trimmed. If this is not sent on the request, the existing first name will be maintained.
lastName true 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.
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.

List Clients

Example Request

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

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

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

Example Response

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

Custom Attributes

The Custom Attribute Object

{
    "id": 1,
    "createdAt": 1588366251,
    "updatedAt": 1588623099,
    "deletedAt": null,
    "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": null,
            "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": null,
            "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": null,
            "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": null,
            "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": null,
            "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": null,
            "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

Invoices

The Invoice Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "clientID":1,
  "advisorID":2,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":1551201267,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "paymentMethod":"ach",
  "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.
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", and "Semi-Annual recurring"
number number This is internal invoice number. Each advisor's invoice count starts att #1001.
paidDate number This is date in unix time that payment was made.
paymentMethod string This is the payment options given for the invoice. It will be one of: "ach", "ccd", or "either".
refundAmount number This is refund amount in cents if a refund has ocurreed on the invoice.
refundDate number This is refund date in unix time if a refund has ocurreed on the invoice.
status string This is status of the invoice. It will be one of: "unpaid" (no action has been taken), "paid" (invoice has been paid and funds have been transferred), "pending_payment" (user has submitted payment and money is transferring to bank account), "pending_processing" (user has submitted payment but subscription has not kicked off yet), "canceled", "refund_failed", "pending_approval", or "approval_rejected".
splitRepCode string This is split/rep code for the invoice that the advisor provided. 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":null,
      "clientID":1,
      "advisorID":2,
      "subscriptionID":1,
      "amount":1000,
      "description":"description",
      "invoiceDate":1551201267,
      "dueDate":1551201267,
      "failedAt":1551201267,
      "frequency":"Monthly recurring",
      "number":1001,
      "paidDate":1551201267,
      "paymentMethod":"ach",
      "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", or "Semi-Annual recurring".
paidAfter empty number This is a unix timestamp to filter by paidDate.
advisorID empty number Filter by invoice advisor.
clientID empty number Filter by invoice client.

Response

Returns a list of invoices sorted by created_at in descending order

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":null,
  "clientID":1,
  "advisorID":2,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":1551201267,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "paymentMethod":"ach",
  "refundAmount":0,
  "refundDate":0,
  "status":"paid",
  "splitRepCode":"",
  "advancedSplitRepCodes":[
    {
        "id":123,
        "createdAt":123456,
        "updatedAt":123456,
        "deletedAt":null,
        "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

Download an Invoice PDF

Example Request

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

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

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

Example Response

N/A (PDF file will be created)

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the invoice to download.

Response

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

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":null,
  "clientID":1,
  "advisorID":2,
  "subscriptionID":1,
  "amount":1000,
  "description":"description",
  "invoiceDate":1551201267,
  "dueDate":1551201267,
  "failedAt":0,
  "frequency":"Monthly recurring",
  "number":1001,
  "paidDate":1551201267,
  "paymentMethod":"ach",
  "refundAmount":0,
  "refundDate":1671201267,
  "status":"refunded",
  "splitRepCode":"",
  "advancedSplitRepCodes":[
    {
        "id":123,
        "createdAt":123456,
        "updatedAt":123456,
        "deletedAt":null,
        "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

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":null,
  "clientID":1,
  "advisorID":2,
  "subscriptionID":0,
  "amount":1000,
  "description":"description",
  "dueDate":1551201267,
  "failedAt":0,
  "frequency":"Single Payment",
  "number":1001,
  "paidDate":0,
  "paymentMethod":"either",
  "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 ind 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.
paymentMethod false string Default is "either". This is the payment options given for the invoice. Must be one of: "ach", "ccd", or "either".

Response

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

Subscriptions

The Subscription Object

{
  "id": 1,
  "createdAt": 1603399833,
  "updatedAt": 1603399833,
  "deletedAt": null,
  "clientID": 2,
  "advisorID": 1,
  "amount": 10000,
  "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.
amount number This is amount of the subscription in cents.
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", and "Semi-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": null,
      "clientID": 2,
      "advisorID": 1,
      "amount": 10000,
      "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", or "Semi-Annual recurring".
advisorID empty number Filter by subscription advisor.
clientID empty number Filter by subscription client.

Response

Returns a list of subscriptions sorted by created_at in descending order

Subscription struct { Amount int64 json:"amount" validate:"required,min=50,max=99999999" DueDate int64 json:"dueDate" validate:"required" UserID uint json:"userID" validate:"required" Frequency string json:"frequency" validate:"required,acceptable_frequency" conform:"trim" SendAsEmail bool json:"sendAsEmail" EmailMessage string json:"emailMessage" PaymentMethod *string json:"paymentMethod" conform:"trim" validate:"omitempty,oneof=ach ccd either" AdvanceBilling bool json:"advanceBilling" BillingPeriods int json:"billingPeriods" ServiceDescriptions []*domain.ServiceDescriptionReq json:"serviceDescriptions" validate:"required" } json:"subscription" validate:"required" OtpInvoice *struct { Amount int64 json:"amount" validate:"required,min=50,max=99999999" DueDate int64 json:"dueDate" validate:"required" ServiceDescriptions []*domain.ServiceDescriptionReq json:"serviceDescriptions" validate:"required" } json:"otpInvoice"

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": null,
  "clientID": 1,
  "advisorID": 2,
  "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", or "Semi-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 ind 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.
paymentMethod false string Default is "either". This is the payment options given for the subscription. Must be one of: "ach", "ccd", or "either".
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.

Agreements

The Agreement Object

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

Attributes

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

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,
      "createdAt":1551201267,
      "updatedAt":1551201267,
      "deletedAt":null,
      "clientID":1,
      "advisorID":2,
      "invoiceID":1,
      "status":"agreement_status_complete",
      "completedAt":1551201267,
      "signingOrderEnabled":true,
      "signers": [
        {
          "agreementID":1,
          "email":"example@advicepay.com",
          "name":"first last",
          "status":"signer_status_complete",
          "signedAt":1551201267,
          "signingOrder":0,
          "title":"Client",
          "externalID":"abc123",
        }
      ],
      "template": {
        "name": "ExampleTemplate",
        "description": "Example eSign Template"
      }
    },
    ...
  ],
  "page":1,
  "perPage":10,
  "totalItems":100,
  "totalPages":10
}

HTTP Request

GET /api/public/v1/agreements

Query Parameters

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

Response

Returns a list of agreements sorted by created_at in descending order

Download an Agreement

Example Request

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

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

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

Example Response

N/A (PDF file will be returned)

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the agreement to download.

Response

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

Transfers

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

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": "",
      "advisorID": 1,
      "agreementID": 1,
      "invoiceID": 1,
      "invoiceNum": 1001,
      "invoiceType": "Single Payment",
      "recurringStartDate": 0,
      "recurringEndDate": 0,
      "invoiceDescription": "description",
      "splitRepCode": "",
    }
  ]
}

Attributes

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

The Transaction Object

Attributes

Value Type Description
id string This is the transaction's unique indentifier.
transferID string This is the ID of the transfer that the transaction belongs to.
transactionType string This is the type of the transaction. Typically one of: "charge", "payment", "refund", "payment_failure_refund"
paymentType string This is the type of payment used for the transaction. It will be either "CC" (credit card) or "ACH" (bank account)
grossAmount number This is the amount chaged in cents.
feeAP number This is the amount of the transaction fee.
feeOverride number This is the calculated percentage firm fee amount. Percentage set under enterprise firm settings.
total number This is the amount for deposit in cents.
paidDate number This is the unix timestamp for when the charge was paid.
clientName string This is the first and last name of the client.
clientExternalID string This is the optional id 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 feild on the advisor object.
advisorID number This is AdvicePay's unique internal advisor ID.
agreementID number This is AdvicePay's unique internal agreement 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",
recurringStartDate number This is the unix timestamp for when the the recurring payment was started.
recurringEndDate number This is the unix timestamp for when the the recurring payment ends.
invoiceDescription string This is the description on the invoice.
splitRepCode string This is 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", nil)
// ...

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

Example Response

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

HTTP Request

GET /api/public/v1/transfers

Query Parameters

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

Response

Returns a list of transfers sorted by arrivalDate in descending order

Deliverables

The Deliverable Template Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "name":"My Template"
  "evidenceTypes":["pdf"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid"
}

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.
evidenceTypes string list The types of evidence allowed when this template is used. Valid values are "pdf", "docx", "image", "url", and "attestation"
intervalType string This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
interval number This is the interval specified in units.
trigger string This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".

The Deliverable Object

{
  "id":1,
  "createdAt":1551201267,
  "updatedAt":1551201267,
  "deletedAt":null,
  "advisorID":1,
  "clientID":2,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":"",
  "urls":[],
  "fileNames":[],
  "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.
status string This is the status of the deliverable. Valid values are "open", "complete", 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 string If the template allows an attestation as evidence, this is the attestation.
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.
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.

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":null,
  "name":"My Template"
  "evidenceTypes":["pdf"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid"
}

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", "evidenceTypes":["pdf"], "intervalType":"years", "interval":1, "trigger":"invoice_paid"}' \
     -X POST
import "net/http"

type createDeliverableTemplateReq struct {
  Name          string
  EvidenceTypes []string
  IntervalType  string
  Interval      uint
  Trigger       string
}

// Marshall request data to JSON string
data := createDeliverableTemplateReq{
  Name:          "My Template",
  EvidenceTypes: []string{"pdf"},
  IntervalType:  "years",
  Interval:      1,
  Trigger:       "invoice_paid",
}
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":null,
  "name":"My Template"
  "evidenceTypes":["pdf"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid"
}

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.
evidenceTypes true string list The types of evidence allowed when this template is used. Valid values are "pdf", "docx", "image", "url", and "attestation"
intervalType true string This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years".
interval true number This is the interval specified in units.
trigger true string This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed".

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
  EvidenceTypes []string
  IntervalType  string
  Interval      uint
  Trigger       string
}

// Marshall request data to JSON string
data := updateDeliverableTemplateReq{
  Name:          "My Template",
  EvidenceTypes: []string{"pdf"},
  IntervalType:  "years",
  Interval:      1,
  Trigger:       "invoice_paid",
}
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":null,
  "name":"My Template"
  "evidenceTypes":["pdf"],
  "intervalType":"years",
  "interval":1,
  "trigger":"invoice_paid"
}

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. If this is not sent on the request, the existing name will be maintained.
evidenceTypes false string list The types of evidence allowed when this template is used. Valid values are "pdf", "docx", "image", "url", and "attestation". If this is not sent on the request, the existing evidence types will be maintained.
intervalType false string This is the interval type used to determine when the deliverable is due. Valid values are "days", "weeks", "months", and "years". If this is not sent on the request, the existing interval type will be maintained.
interval false number This is the interval specified in units. If this is not sent on the request, the existing interval will be maintained.
trigger false string This is the trigger used to calculate when the deliverable is due. Valid values are "invoice_paid" and "agreement_signed". If this is not sent on the request, the existing trigger will be maintained.

Response

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

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":null,
      "name":"My Template"
      "evidenceTypes":["pdf"],
      "intervalType":"years",
      "interval":1,
      "trigger":"invoice_paid"
    },
    ...
  ],
  "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

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":null,
  "advisorID":1,
  "clientID":2,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":"",
  "urls":[],
  "fileNames":[],
  "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":null,
  "advisorID":1,
  "clientID":2,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":"",
  "urls":[],
  "fileNames":[],
  "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":null,
  "advisorID":1,
  "clientID":2,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":"",
  "urls":[],
  "fileNames":[],
  "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.

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":null,
      "advisorID":1,
      "clientID":2,
      "status":"open",
      "templateName":"My Template",
      "triggerDate":1234567,
      "dueDate":1234567,
      "attestation":"",
      "urls":[],
      "fileNames":[],
      "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
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

Response

Returns a list of deliverables sorted by created_at in descending order

Submit a deliverable

Example Request

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

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

// Marshall request data to JSON string
data := submitDeliverableReq{
  Title: "My title",
  Description: "My description",
  Attestation: "My attestation",
  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":null,
  "advisorID":1,
  "clientID":2,
  "status":"open",
  "templateName":"My Template",
  "triggerDate":1234567,
  "dueDate":1234567,
  "attestation":"My attestation",
  "urls":["https://www.advicepay.com"],
  "fileNames":["file1.pdf", "file2.pdf"],
  "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
title true string This is the advisor-defined title of the deliverable. It should be a brief summary.
description false string This is the advisor-defined description of the deliverable. It should fill in any details missing from the title.
attestation false string This is the attestation 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.

Get the file download URL

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.

Other Objects

The Signer Object

{
  "agreementID":1,
  "email":"example@advicepay.com",
  "name":"first last",
  "status":"signer_status_complete",
  "signedAt":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.
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":null,
  "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.

Pagination

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

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

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

Errors

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

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

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

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

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

Validation Messages

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

Single Sign On

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

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

Requesting Access

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

HTTP Request

POST /auth/sso

Query Parameters

Parameter Required Description
source true The company slug used to determine which certificate to validate against. 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.