Data

---

This integration offers direct access to internally stored data

• Credentials
  • Search
  • Store
  • Show
  • Update
• Form Submissions
  • Store
  • Show
  • Update
• User Tokens
  • Search
  • Store
  • Show
• Usages
  • Search
  • Store
  • Show

Credentials

Credentials encrypt and store sensitive data and service settings for customers.

The api allows passing a sso_user_id value which can be searched later by the client for obtaining a user's integration credentials. Alternatively, a client can locally store the saved credential uuid for later retrieval.

Search

If the client does not locally store a credential's uuid, one can be found by searching for the sso_user_id value

Endpoint

Method	URI	Headers
GET	/api/v1/integrations/data/credentials	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
    "sso_user_id": 17
}

Example Response Content

The response will contain an array of credential objects

{
    "data": [
        {
            "uuid": "e2895de0-a18f-11e9-81b2-3d67761ee2f6",
            "sso_user_id": 17,
            "client_id": null,
            "integration_key": null,
            "value": {
                "velocify": {
                    "enabled": "1"
                },
                "lendingqb": {
                    "enabled": "1",
                    "username": "info@test.com"
                }
            },
            "created_at": "2019-07-08T14:51:36.000000Z",
            "updated_at": "2019-07-08T16:56:13.000000Z"
        }
    ]
}

Store

Note that credentials are encrypted automatically. Simply post the data directly.

Endpoint

Method	URI	Headers
POST	/api/v1/integrations/data/credentials	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
    "sso_user_id": 17,
    "value": {
        "lendingqb": {
          "username": "abc123"
        }
    }
}

Example Response Content

The response will contain the created credential object

{
    "data": {
        "uuid": "b2b0c8e0-a1bd-11e9-80f5-8374f81ca53d",
        "sso_user_id": "111",
        "client_id": null,
        "integration_key": null,
        "value": {
            "lendingqb": {
                "username": "33"
            }
        },
        "created_at": "2019-07-08T20:19:33.000000Z",
        "updated_at": "2019-07-08T20:19:33.000000Z"
    }
}

Show

Find a credential via uuid

Endpoint

Method	URI	Headers
POST	/api/v1/integrations/data/credentials/{uuid}	{"Authorization": "Bearer {access_token}"}

Example Response Content

The response will contain the credential object

{
    "data": {
        "uuid": "b2b0c8e0-a1bd-11e9-80f5-8374f81ca53d",
        "sso_user_id": "111",
        "client_id": null,
        "integration_key": null,
        "value": {
            "lendingqb": {
                "username": "33"
            }
        },
        "created_at": "2019-07-08T20:19:33.000000Z",
        "updated_at": "2019-07-08T20:19:33.000000Z"
    }
}

Update

Since the credential value contains the full payload of data, be sure to pull the existing data, overwrite it, then pass the full payload back when updating field values.

Endpoint

Method	URI	Headers
PATCH	/api/v1/integrations/data/credentials/{uuid}	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
    "sso_user_id": 17,
    "value": {
        "lendingqb": {
          "username": "newuser"
        }
    }
}

Example Response Content

The response will contain the credential object

{
    "data": {
        "uuid": "b2b0c8e0-a1bd-11e9-80f5-8374f81ca53d",
        "sso_user_id": "111",
        "client_id": null,
        "integration_key": null,
        "value": {
            "lendingqb": {
                "username": "newuser"
            }
        },
        "created_at": "2019-07-08T20:19:33.000000Z",
        "updated_at": "2019-07-08T20:19:33.000000Z"
    }
}

Form Submissions

Form submissions are a great way to store payload data and form credentials as it passes between services we offer.

Store a Form Submission

Each form submission can consist of a data object, credentials object, or both.

Note that within the internal database, values stored as credentials are encrypted. However when posting or retrieving this data, those values will be automatically encrypted/decrypted.

On a successful save, a uuid for the form submission will be stored. This will be used by following services looking to retrieve this form information.

Endpoint

Method	URI	Headers
POST	/api/v1/integrations/data/form-submissions	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
    "data"    : {
      "first_name": "John",
      "last_name": "Doe"
    },
    "credentials"    : {
      "lendingqb_username": "demouser",
      "lendingqb_password": "password",
      "plaid_secret_key": "ABCDEFG12345"
    }
}

Example Response Content

{
    "uuid"    : "21e60a62-eee1-4793-a5d2-666b2eb8466a",
    "data"    : {
      "first_name": "John",
      "last_name": "Doe"
    },
    "credentials"    : {
      "lendingqb_username": "demouser",
      "lendingqb_password": "password",
      "plaid_secret_key": "ABCDEFG12345"
    }
}

Show a Form Submission

Endpoint

Method	URI	Headers
GET	/api/v1/integrations/data/form-submissions/{formSubmissionId}	{"Authorization": "Bearer {access_token}"}

Example Response Content

{
    "uuid"    : "21e60a62-eee1-4793-a5d2-666b2eb8466a",
    "data"    : {
      "first_name": "John",
      "last_name": "Doe"
    },
    "credentials"    : {
      "lendingqb_username": "demouser",
      "lendingqb_password": "password",
      "plaid_secret_key": "ABCDEFG12345"
    }
}

Store a Form Submission

Each form submission can consist of a data object, credentials object, or both.

Note that within the internal database, values stored as credentials are encrypted. However when posting or retrieving this data, those values will be automatically encrypted/decrypted.

On a successful save, a uuid for the form submission will be stored. This will be used by following services looking to retrieve this form information.

Endpoint

Method	URI	Headers
PATCH	/api/v1/integrations/data/form-submissions/{formSubmissionId}	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
    "data"    : {
      "first_name": "Mike",
      "last_name": "Doe"
    }
}

Example Response Content

{
    "uuid"    : "21e60a62-eee1-4793-a5d2-666b2eb8466a",
    "data"    : {
      "first_name": "Mike",
      "last_name": "Doe"
    },
    "credentials"    : {
      "lendingqb_username": "demouser",
      "lendingqb_password": "password",
      "plaid_secret_key": "ABCDEFG12345"
    }   
}

User Tokens

Certain services or applications may require a unique token to allow us to link for a specific account (Zapier for example). UserTokens allow us to create a token and link it to a specific user based on their sso_user_id.

Search

A user's token can be found by searching for the sso_user_id value

Endpoint

Method	URI	Headers
GET	/api/v1/integrations/data/user-tokens	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
    "sso_user_id": 17
}

Example Response Content

The response will contain an array of credential objects

{
    "data": [
        {
            "uuid": "e2895de0-a18f-11e9-81b2-3d67761ee2f6",
            "sso_user_id": 17,
            "token": "d755bcf4-414e-4c35-baef-bd8da7f56d56",
            "integration_key": "zapier",
            "type": null
        }
    ]
}

Store a User Token

A token can be stored by passing the sso_user_id and integration_key or type to indicate what the use of this token is.

Endpoint

Method	URI	Headers
POST	/api/v1/integrations/data/user-tokens	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
      "sso_user_id": 17,
      "integration_key": "zapier"
}

Example Response Content

{
    "data"    : {
      "uuid": "e2895de0-a18f-11e9-81b2-3d67761ee2f6",
      "sso_user_id": 17,
      "token": "d755bcf4-414e-4c35-baef-bd8da7f56d56",
      "integration_key": "zapier",
      "type": null
    }
}

Show a User Token

Endpoint

Method	URI	Headers
GET	/api/v1/integrations/data/user-tokens/{userTokenId}	{"Authorization": "Bearer {access_token}"}

Example Response Content

{
    "data"    : {
      "uuid": "e2895de0-a18f-11e9-81b2-3d67761ee2f6",
      "sso_user_id": 17,
      "token": "d755bcf4-414e-4c35-baef-bd8da7f56d56",
      "integration_key": "zapier",
      "type": null
    }
}

Usages

Records used for viewing customer service usage from third-party integrations for billing use

Search

Usages can be found by searching for the sso_user_id value

Endpoint

Method	URI	Headers
GET	/api/v1/integrations/data/usages	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
    "sso_user_id": 17
}

Example Response Content

The response will contain an array of credential objects

{
    "data": [
        {
            "uuid": "e2895de0-a18f-11e9-81b2-3d67761ee2f6",
            "sso_user_id": 17,
            "integration_key": "zapier",
            "data": {...}
        }
    ]
}

Store a Usage log

A token can be stored by passing the sso_user_id and integration_key or type to indicate what the use of this token is.

Note: Like in the example below, the data property will likely contain some specific service information to help in determining the proper billing method for the usage.

Endpoint

Method	URI	Headers
POST	/api/v1/integrations/data/usages	{"Authorization": "Bearer {access_token}"}

Example Data Params

{
      "sso_user_id": 17,
      "integration_key": "plaid",
      "data": {
        "action": "verification-of-assets"
      }
}

Example Response Content

{
    "data"    : {
      "uuid": "e2895de0-a18f-11e9-81b2-3d67761ee2f6",
      "sso_user_id": 17,
      "integration_key": "plaid",
      "data": {...}
    }
}

Show a Usage record

Endpoint

Method	URI	Headers
GET	/api/v1/integrations/data/usages/{usageId}	{"Authorization": "Bearer {access_token}"}

Example Response Content

{
    "data"    : {
      "uuid": "e2895de0-a18f-11e9-81b2-3d67761ee2f6",
      "sso_user_id": 17,
      "integration_key": "zapier",
      "data": {...}
    }
}