Shell HTTP JavaScript Node.JS Ruby Python Java Go

Invitations v0.1.12

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

This API allows digital banking customers to send invitations to other people to become joint owners on personal accounts or to become authorized signers of business organizations.

When a user creates a new invitation (createInvitation below), the service sends an email, on behalf of the financial institution, to the invitee's email address with instructions to accept the invitation by visiting a web page. An invitation consists of four key data items which the invitee must supply in order to accept the invitation:

  1. First name
  2. Last name
  3. Last four digits of the invitee's government ID (typically, the last four digits of their Social Security Number)
  4. A pass phrase or "shared secret"

Invitation States may be one of the following:

The invitation also references the account or organization they are being invited to join, depending on the type of the invitation. For joint owner invitations, other existing joint owners on the account can see outstanding invitations for the account. For authorized signer invitation, other existing joint owners can see outstanding invitations for the business organization.

The Inviter should share the secret with the invitee through another secure channel (such as face to face or in a phone conversation) so that unauthorized people cannot accept the invitation even if they know the other three items.

The Inviter can revoke an invitation if the state of the invitation is sent.

When the invitee visits the web form listed in their invitation email, they fill out the four data fields to accept. The client can use the verifyInvitation operation below to determine if the invitee entered the data including the shared secret correctly. If they enter the data correctly, the invitation is accepted.

If not already users, invitees must register as users on the financial institution's digital banking platform in order to assume these roles. Unverified users must also execute the financial institution's identity verification process before they are added as a joint user or authorized signer. Once added as a joint user or authorized signer, the invitation is completed.

Inviters can update an invitation's four data fields. If the email differs, the invitation is resent. Inviters can also request an invitation be resent or revoke an invitation. Unaccepted invitations expire after some time (such as 30 or 45 days).

Download OpenAPI Definition (YAML)

Base URLs:

Terms of service

Email: Apiture Web: Apiture

Authentication

Scope Scope Description
banking/read Read access to invitations
banking/write Write (update) access to invitations
banking/delete Delete access to invitations
banking/full Full access to invitations

API

The Invitations API

getApi

Code samples

# You can also use wget
curl -X GET /invitations/ \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY'

GET /invitations/ HTTP/1.1

Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY'

};

$.ajax({
  url: '/invitations/',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY'

};

fetch('/invitations/',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY'
}

result = RestClient.get '/invitations/',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY'
}

r = requests.get('/invitations/', params={

}, headers = headers)

print r.json()

URL obj = new URL("/invitations/");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/invitations/", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Top-level resources and operations in this API

GET /

Return links to the top-level resources and operations in this API.

Example responses

200 Response

{
  "id": "apiName",
  "name": "API name",
  "apiVersion": "1.0.0",
  "_profile": "https://api.apiture.com/schemas/common/root/v1.0.0/profile.json",
  "_links": {}
}

Responses

StatusDescription
200 OK
OK
Schema: root

getApiDoc

Code samples

# You can also use wget
curl -X GET /invitations/apiDoc \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

GET /invitations/apiDoc HTTP/1.1

Accept: application/json

var headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

$.ajax({
  url: '/invitations/apiDoc',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

fetch('/invitations/apiDoc',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'API-Key' => 'API_KEY'
}

result = RestClient.get '/invitations/apiDoc',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'API-Key': 'API_KEY'
}

r = requests.get('/invitations/apiDoc', params={

}, headers = headers)

print r.json()

URL obj = new URL("/invitations/apiDoc");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "API-Key": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/invitations/apiDoc", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Return API definition document

GET /apiDoc

Return the OpenAPI document that describes this API.

Example responses

200 Response

{}

Responses

StatusDescription
200 OK
OK
Schema: Inline

Response Schema

Invitation

Invitations

getInvitations

Code samples

# You can also use wget
curl -X GET /invitations/invitations \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET /invitations/invitations HTTP/1.1

Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/invitations/invitations',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/invitations/invitations',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/invitations/invitations',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/invitations/invitations', params={

}, headers = headers)

print r.json()

URL obj = new URL("/invitations/invitations");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/invitations/invitations", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Return a collection of invitations

GET /invitations

Return a paginated sortable filterable searchable collection of invitations. The links in the response include pagination links.

Parameters

Parameter Description
start
(query)
integer(int64)
The zero-based index of the first invitation item to include in this page. The default 0 denotes the beginning of the collection.
limit
(query)
integer(int32)
The maximum number of invitation representations to return in this page.
sortBy
(query)
string
Optional sort criteria. See sort criteria format, such as ?sortBy=field1,-field2.
filter
(query)
string
Optional filter criteria. See filtering.
q
(query)
string
Optional search string. See searching.
pendingInvitations
(query)
boolean
Subset the invitations collection to those pending invitations for the currently authenticated user. These are invitations that have been verified by the authenticated user but still require some user action to complete the invitation process. This is combined with an implicit and with other filters if they are used. See filtering.
accountUri
(query)
string
Subset the invitations collection to those with this accountUri value. Use | to separate multiple values. For example, ?accountUri=https://api.apiture.com/accounts/accounts/0399abed-fd3d-4830-a88b-30f38b8a365c will match only items whose accountUri is https://api.apiture.com/accounts/accounts/0399abed-fd3d-4830-a88b-30f38b8a365c. This is combined with an implicit and with other filters if they are used. See filtering.
organizationUri
(query)
string
Subset the invitations collection to those with this organizationUri value. Use | to separate multiple values. For example, ?organizationUri=https://api.apiture.com/organizations/organizations/0399abed-fd3d-4830-a88b-30f38b8a365c will match only items whose organizationUri is https://api.apiture.com/organizations/organizations/0399abed-fd3d-4830-a88b-30f38b8a365c. This is combined with an implicit and with other filters if they are used. See filtering.
state
(query)
string
Subset the invitations collection to those whose state matches this value. Use | to separate multiple values. For example, ?state=sent will match only items whose state is sent; ?state=sent|accepted will match items whose state is sent or accepted. This is combined with an implicit and with other filters if they are used. See filtering.
Enumerated values:
sent
accepted
completed
revoked
expired
type
(query)
string
Subset the invitations collection to those whose type matches this value. Use | to separate multiple values. For example, ?type=joint will match only items whose type is joint; ?state=joint|authorizedSigner will match items whose type is joint or authorizedSigner. This is combined with an implicit and with other filters if they are used. See filtering.
Enumerated values:
joint
authorizedSigner
firstName
(query)
string
Subset the invitations collection to those with this firstName value. Use | to separate multiple values. For example, ?firstName=John will match only items whose name is John; ?firstName=John|Tom will match items whose name is John or Tom. This is combined with an implicit and with other filters if they are used. See filtering.
lastName
(query)
string
Subset the invitations collection to those with this lastName value. Use | to separate multiple values. For example, ?lastName=Bartell will match only items whose name is Bartell; ?lastName=Bartell|Smith will match items whose name is Bartell or Smith. This is combined with an implicit and with other filters if they are used. See filtering.
emailAddress
(query)
string
Subset the invitations collection to those with this emailAddress value. Use | to separate multiple values. For example, ?emailAddress=johnsmith@email.com will match only items whose emailAddress is johnsmith@email.com; ?emailAddress=johnsmith@email.com|tomjones@email.com will match items whose emailAddress is johnsmith@email.com or tomjones@email.com. This is combined with an implicit and with other filters if they are used. See filtering.

Example responses

200 Response

{
  "_profile": "https://api.apiture.com/schemas/invitations/invitations/v1.0.0/profile.json",
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "invitations",
  "_links": {
    "self": {
      "href": "/invitations/invitations?start=10&limit=10"
    },
    "first": {
      "href": "/invitations/invitations?start=0&limit=10"
    },
    "next": {
      "href": "/invitations/invitations?start=20&limit=10"
    },
    "collection": {
      "href": "/invitations/invitations"
    }
  },
  "_embedded": {
    "items": [
      {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://api.apiture.com/schemas/invitations/invitation/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/invitations/invitations/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://api.apiture.com/schemas/invitations/invitation/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/invitations/invitations/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    ]
  }
}

Responses

StatusDescription
200 OK
OK
Schema: invitations
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

createInvitation

Code samples

# You can also use wget
curl -X POST /invitations/invitations \
  -H 'Content-Type: application/hal+json' \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /invitations/invitations HTTP/1.1

Content-Type: application/hal+json
Accept: application/hal+json

var headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/invitations/invitations',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}';
const headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/invitations/invitations',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/hal+json',
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/invitations/invitations',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/hal+json',
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/invitations/invitations', params={

}, headers = headers)

print r.json()

URL obj = new URL("/invitations/invitations");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/hal+json"},
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/invitations/invitations", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Create a new invitation

POST /invitations

Create a new invitation resource and send the invitation email to the invitee.

Body parameter

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}

Parameters

Parameter Description
body
(body)
createInvitation (required)
The data necessary to create a new invitation.

Example responses

201 Response

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "verificationCount": 0,
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}

Responses

StatusDescription
201 Created
Created
Schema: invitation
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse

Response Headers

StatusDescription
201 Location string uri
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with scheme://host
201 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for PUT or PATCH operations which update the resource.

getInvitation

Code samples

# You can also use wget
curl -X GET /invitations/invitations/{invitationId} \
  -H 'Accept: application/hal+json' \
  -H 'If-None-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET /invitations/invitations/{invitationId} HTTP/1.1

Accept: application/hal+json
If-None-Match: string

var headers = {
  'Accept':'application/hal+json',
  'If-None-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/invitations/invitations/{invitationId}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'If-None-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/invitations/invitations/{invitationId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'If-None-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/invitations/invitations/{invitationId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'If-None-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/invitations/invitations/{invitationId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("/invitations/invitations/{invitationId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "If-None-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/invitations/invitations/{invitationId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Fetch a representation of this invitation

GET /invitations/{invitationId}

Return a HAL representation of this invitation resource.

Parameters

Parameter Description
invitationId
(path)
string (required)
The unique identifier of this invitation. This is an opaque string.
If-None-Match
(header)
string
The entity tag that was returned in the ETag response. If the resource's current entity tag matches, the GET will return 304 (Not Modified) and no response body, else the resource representation will be returned.

Example responses

200 Response

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "verificationCount": 0,
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}

Responses

StatusDescription
200 OK
OK
Schema: invitation
304 Not Modified
Not Modified. The resource has not been modified since it was last fetched.
404 Not Found
Not Found. There is no such invitation resource at the specified {invitationId}. The _error field in the response will contain details about the request error.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for PUT or PATCH operations which update this invitation resource.

deleteInvitation

Code samples

# You can also use wget
curl -X DELETE /invitations/invitations/{invitationId} \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

DELETE /invitations/invitations/{invitationId} HTTP/1.1

var headers = {
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/invitations/invitations/{invitationId}',
  method: 'delete',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/invitations/invitations/{invitationId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/invitations/invitations/{invitationId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('/invitations/invitations/{invitationId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("/invitations/invitations/{invitationId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "/invitations/invitations/{invitationId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Delete this invitation resource

DELETE /invitations/{invitationId}

Delete this invitation resource and any resources that are owned by it.

Parameters

Parameter Description
invitationId
(path)
string (required)
The unique identifier of this invitation. This is an opaque string.

Responses

StatusDescription
204 No Content
No Content. The resource was deleted successfully.

revokeInvitation

Code samples

# You can also use wget
curl -X POST /invitations/revoked?invitation=string \
  -H 'Accept: application/hal+json' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /invitations/revoked?invitation=string HTTP/1.1

Accept: application/hal+json
If-Match: string

var headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/invitations/revoked',
  method: 'post',
  data: '?invitation=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/invitations/revoked?invitation=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/invitations/revoked',
  params: {
  'invitation' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'If-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/invitations/revoked', params={
  'invitation': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("/invitations/revoked?invitation=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/invitations/revoked", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Revoke an Invitation

POST /revoked

Revoke an invitation that is eligible to be revoked. Only Invitations which are sent can be revoked. This operation is invoked from the apiture:revoke link on an Invitation, which only exists if the action is allowed. This changes the state to revoked.

Parameters

Parameter Description
invitation
(query)
string (required)
A server-supplied value which identifies the invitation instance.
If-Match
(header)
string
The entity tag that was returned in the ETag response. This must match the current entity tag of the resource.

Example responses

200 Response

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "verificationCount": 0,
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}

Responses

StatusDescription
200 OK
OK
Schema: invitation
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
409 Conflict
Conflict. The request to change the state of the invitation is not allowed. For example, one cannot change the state of a completed invitation, or change a non-sent invitation to revoked. The _error field in the response will contain details about the request error.
Schema: errorResponse
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

sendInvitation

Code samples

# You can also use wget
curl -X POST /invitations/sent?invitation=string \
  -H 'Accept: application/hal+json' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /invitations/sent?invitation=string HTTP/1.1

Accept: application/hal+json
If-Match: string

var headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/invitations/sent',
  method: 'post',
  data: '?invitation=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/invitations/sent?invitation=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/invitations/sent',
  params: {
  'invitation' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'If-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/invitations/sent', params={
  'invitation': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("/invitations/sent?invitation=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/invitations/sent", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Send an Invitation

POST /sent

This action will re-send an already sent invitation to the invitee. Only Invitations which are already sent can be re-sent. This operation is invoked from the apiture:send link on an Invitation, which only exists if the action is allowed. There is a configurable limit of times that an invitation can be re-sent.

Parameters

Parameter Description
invitation
(query)
string (required)
A server-supplied value which identifies the invitation instance.
If-Match
(header)
string
The entity tag that was returned in the ETag response. This must match the current entity tag of the resource.

Example responses

200 Response

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "verificationCount": 0,
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}

Responses

StatusDescription
200 OK
OK
Schema: invitation
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
409 Conflict
Conflict. The request to change the state of the invitation is not allowed. For example, one cannot change the state of a completed invitation, or change a non-sent invitation to revoked. The _error field in the response will contain details about the request error.
Schema: errorResponse
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

completeInvitation

Code samples

# You can also use wget
curl -X POST /invitations/completed?invitation=string \
  -H 'Accept: application/hal+json' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST /invitations/completed?invitation=string HTTP/1.1

Accept: application/hal+json
If-Match: string

var headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/invitations/completed',
  method: 'post',
  data: '?invitation=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('/invitations/completed?invitation=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/invitations/completed',
  params: {
  'invitation' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json',
  'If-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/invitations/completed', params={
  'invitation': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("/invitations/completed?invitation=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/hal+json"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/invitations/completed", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Complete an Invitation

POST /completed

Complete an invitation that is eligible to be completed. Only Invitations which are accepted can be completed. This admin operation is invoked from the apiture:complete link on an Invitation, which only exists if the action is allowed. This changes the state to completed. Completed means the desired result (user added as joint owner or authorized signer) has been completed.

Parameters

Parameter Description
invitation
(query)
string (required)
A server-supplied value which identifies the invitation instance.
If-Match
(header)
string
The entity tag that was returned in the ETag response. This must match the current entity tag of the resource.

Example responses

200 Response

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "verificationCount": 0,
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}

Responses

StatusDescription
200 OK
OK
Schema: invitation
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
409 Conflict
Conflict. The request to change the state of the invitation is not allowed. For example, one cannot change the state of a completed invitation, or change a non-sent invitation to revoked. The _error field in the response will contain details about the request error.
Schema: errorResponse
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

Verification

Invitation Verifications

verifyInvitation

Code samples

# You can also use wget
curl -X POST /invitations/verifications \
  -H 'Content-Type: application/hal+json' \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY'

POST /invitations/verifications HTTP/1.1

Content-Type: application/hal+json
Accept: application/hal+json

var headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'API-Key':'API_KEY'

};

$.ajax({
  url: '/invitations/verifications',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{
  "firstName": "John",
  "lastName": "Smith",
  "identification": "4758",
  "sharedSecret": "obsolete obese octopus",
  "invitationId": "d62c0701-0d74-4836-83f9-ebf3709442ea"
}';
const headers = {
  'Content-Type':'application/hal+json',
  'Accept':'application/hal+json',
  'API-Key':'API_KEY'

};

fetch('/invitations/verifications',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/hal+json',
  'Accept' => 'application/hal+json',
  'API-Key' => 'API_KEY'
}

result = RestClient.post '/invitations/verifications',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/hal+json',
  'Accept': 'application/hal+json',
  'API-Key': 'API_KEY'
}

r = requests.post('/invitations/verifications', params={

}, headers = headers)

print r.json()

URL obj = new URL("/invitations/verifications");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/hal+json"},
        "Accept": []string{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/invitations/verifications", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Verify an Invitation

POST /verifications

Verify an Invitation that is eligible to be verified. Only Invitations that are in a state of sent can be verified. Required fields are firstName, lastName, identification and sharedSecret. This operation will increase the verificationCount for any Invitation that contains the same firstName, lastName and identification values supplied in the request. If the key data matches and the optional invitationId field was not supplied, all sent invitations that match will be marked as accepted. If invitationId was supplied, the key data will be checked against that invitation only. Invitations that are revoked or expired are not processed.

Body parameter

{
  "firstName": "John",
  "lastName": "Smith",
  "identification": "4758",
  "sharedSecret": "obsolete obese octopus",
  "invitationId": "d62c0701-0d74-4836-83f9-ebf3709442ea"
}

Parameters

Parameter Description
body
(body)
verification (required)
The data necessary to verify an invitation.

Example responses

200 Response

{
  "firstName": "John",
  "lastName": "Smith",
  "identification": "4758",
  "sharedSecret": "obsolete obese octopus",
  "invitationId": "d62c0701-0d74-4836-83f9-ebf3709442ea"
}

Responses

StatusDescription
200 OK
OK - the invitation was matched and accepted.
Schema: verification
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
429 Too Many Requests
Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a period of time has passed.
Schema: errorResponse

Schemas

verification

{
  "firstName": "John",
  "lastName": "Smith",
  "identification": "4758",
  "sharedSecret": "obsolete obese octopus",
  "invitationId": "d62c0701-0d74-4836-83f9-ebf3709442ea"
}

Verification

Representation of verification resources.

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
firstName string (required)
The first name of the invitee.
lastName string (required)
The lastName name of the invitee.
identification string (required)
The last 4 digits of the government ID (SSN or other ID) of invitee.
sharedSecret string (required)
A string shared by the inviter with the invitee to verify their identity.
minLength: 8
invitationId string
A optional id of an invitation resource. If included, the service will compare the key data against this invitation only.

createInvitation

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "verificationCount": 0,
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}

Create Invitation

Representation used to create a new Invitation.

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
The unique identifier for this Invitation resource. This is an immutable opaque string.
firstName string (required)
The first name of the invitee.
lastName string (required)
The lastName name of the invitee.
identification string (required)
The last 4 digits of the government ID (SSN or other ID) of invitee.
sharedSecret string (required)
A string shared by the inviter with the invitee to verify their identity.
minLength: 8
emailAddress string (required)
The email address of the invitee.
type string (required)
The type of invitation.


Enumerated values:
joint
authorizedSigner

accountUri string
If type is joint, this is the uri of the account the invitee is being invited to.
organizationUri string
If type is authorizedSigner, this is the uri of the organization the invitee is being invited to.
state string
The state of invitation.


Enumerated values:
sent
accepted
completed
revoked
expired

inviterFullName string (required)
The full name of the user sending the invitation.
verificationCount integer
The count of attempted verifications of this invitation.
read-only
createdBy string
The unique User Id of the person who created the Invitation.
createdAt string(date-time)
The date-time when the invitation was created. This is in RFC 3339format, UTC. This is derived and immutable.
updatedAt string(date-time)
The date-time when the invitation was last updated. This is in RFC 3339format, UTC. This is derived and immutable.
expiresAt string(date-time)
The date-time when the invitation will expire. This is in RFC 3339format, UTC. This is derived and immutable.

invitation

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  },
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "identification": "string",
  "sharedSecret": "stringst",
  "emailAddress": "string",
  "type": "joint",
  "accountUri": "string",
  "organizationUri": "string",
  "state": "sent",
  "inviterFullName": "string",
  "verificationCount": 0,
  "createdBy": "string",
  "createdAt": "2019-10-29T18:22:17Z",
  "updatedAt": "2019-10-29T18:22:17Z",
  "expiresAt": "2019-10-29T18:22:17Z"
}

Invitation

Representation of invitation resources.

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
The unique identifier for this Invitation resource. This is an immutable opaque string.
firstName string
The first name of the invitee.
lastName string
The lastName name of the invitee.
identification string
The last 4 digits of the government ID (SSN or other ID) of invitee.
sharedSecret string
A string shared by the inviter with the invitee to verify their identity.
minLength: 8
emailAddress string
The email address of the invitee.
type string
The type of invitation.


Enumerated values:
joint
authorizedSigner

accountUri string
If type is joint, this is the uri of the account the invitee is being invited to.
organizationUri string
If type is authorizedSigner, this is the uri of the organization the invitee is being invited to.
state string
The state of invitation.


Enumerated values:
sent
accepted
completed
revoked
expired

inviterFullName string
The full name of the user sending the invitation.
verificationCount integer
The count of attempted verifications of this invitation.
read-only
createdBy string
The unique User Id of the person who created the Invitation.
createdAt string(date-time)
The date-time when the invitation was created. This is in RFC 3339format, UTC. This is derived and immutable.
updatedAt string(date-time)
The date-time when the invitation was last updated. This is in RFC 3339format, UTC. This is derived and immutable.
expiresAt string(date-time)
The date-time when the invitation will expire. This is in RFC 3339format, UTC. This is derived and immutable.

invitations

{
  "_profile": "https://api.apiture.com/schemas/invitations/invitations/v1.0.0/profile.json",
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "invitations",
  "_links": {
    "self": {
      "href": "/invitations/invitations?start=10&limit=10"
    },
    "first": {
      "href": "/invitations/invitations?start=0&limit=10"
    },
    "next": {
      "href": "/invitations/invitations?start=20&limit=10"
    },
    "collection": {
      "href": "/invitations/invitations"
    }
  },
  "_embedded": {
    "items": [
      {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://api.apiture.com/schemas/invitations/invitation/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/invitations/invitations/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://api.apiture.com/schemas/invitations/invitation/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/invitations/invitations/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    ]
  }
}

Invitation Collection

Collection of invitations. The items in the collection are ordered in the _embedded.items array; the name is invitations. The top-level _links object may contain pagination links (self, next, prev, first, last, collection.)

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
Embedded objects.
» items [invitation]
An array containing a page of invitation items.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
count integer
The number of items in the collection. This value is optional and my be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter.
start integer
The start index of this page of items.
limit integer
The maximum number of items per page.
name string
The name of the collection.

root

{
  "id": "apiName",
  "name": "API name",
  "apiVersion": "1.0.0",
  "_profile": "https://api.apiture.com/schemas/common/root/v1.0.0/profile.json",
  "_links": {}
}

API Root

A HAL response, with hypermedia _links for the top-level resources and operations in API.

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
This API's unique ID.
name string
This API's name.
apiVersion string
This API's version.

errorResponse

{
  "_profile": "https://api.apiture.com/schemas/common/errorResponse/v1.0.0/profile.json",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://api.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  }
}

Error Response

Describes an error response, typically returned on 4xx or 5xx errors from API operations. The _error object contains the error details.

Properties

NameDescription
_links object
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
» additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.

error

{
  "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
  "message": "The value for deposit must be greater than 0.",
  "statusCode": 422,
  "type": "positiveNumberRequired",
  "attributes": {
    "value": -125.5
  },
  "remediation": "Provide a value which is greater than 0",
  "occurredAt": "2018-01-25T05:50:52.375Z",
  "_links": {
    "describedby": {
      "href": "https://developer.apiture.com/errors/positiveNumberRequired"
    }
  },
  "_embedded": {
    "errors": []
  }
}

Error

Describes an error in an API request or in a service called via the API.

Properties

NameDescription
message string (required)
A localized message string describing the error condition.
_id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
errors [error]
An optional array of nested error objects. This property is not always present.
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
Embedded objects. An error object may contain nested errors. For example, an API which validates its request body may find multiple errors in the request, which are returned with an error response with nested errors. These are held in an items array of errorResponse objects. _embedded or _embedded.items may not exist if the error does not have nested errors. This property is deprecated; use see error.errors instead.
» items [errorResponse]
An array of error objects.

attributes

{}

Attributes

An optional map of name/value pairs which contains additional dynamic data about the resource.

Properties

{
  "property1": {
    "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
    "title": "Applicant"
  },
  "property2": {
    "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
    "title": "Applicant"
  }
}

Links

An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.

Properties

NameDescription
additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.

{
  "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
  "title": "Applicant"
}

Link

Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.

Properties

NameDescription
href string(uri) (required)
The URI or URI template for the resource/operation this link refers to.
type string
The media type for the resource.
templated boolean
If true, the link's href is a URI template.
title string
An optional human-readable localized title for the link.
deprecation string(uri)
If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.
profile string(uri)
The URI of a profile document, a JSON document which describes the target resource/operation.

localizedLabels

{
  "property1": {
    "label": "Limited Liability Corporation",
    "description": "string",
    "language": "en-us",
    "code": "31"
  },
  "property2": {
    "label": "Limited Liability Corporation",
    "description": "string",
    "language": "en-us",
    "code": "31"
  }
}

Localized Labels

A map that defines lables for an enumeration or other item in a JSON schema. This is a map which maps enumeration schema names to an localizedLabel object.

Properties

NameDescription
additionalProperties localizedLabel
A localized label and optional description for localizable content defined in this API.

localizedLabel

{
  "label": "Limited Liability Corporation",
  "description": "string",
  "language": "en-us",
  "code": "31"
}

Localized Label

A localized label and optional description for localizable content defined in this API.

Properties

NameDescription
label string
A localized label or title which may be used labels or other UI controls which present a value.
description string
A more detailed localized description of a localizable label.
language string
The actual natural language tag to which this localized label is associated, as per RFC 7231
code string
If the localized value is associated with an external standard, this is a lookup code or key or URI for that value.