Invitations v0.3.4
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. The link in the generated email includes parameters that describe the invitation resource, including but not limited to invitationId
. The invitationId
is required on the verifyInvitation
operation below.
The "shared secret" is a string the invitee shares the inviter to verify their identity. See (sharedSecret
below)
Invitation States may be one of the following:
sent
Invitation sent to inviteeaccepted
Invitation accepted by inviteecompleted
Invitee has been added to their invited rolerevoked
Invitation revoked by inviterexpired
Invitation expired
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.
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 enter the sharedSecret
to accept. The client can use the verifyInvitation
operation below to determine if the invitee entered the 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 shared secret. Inviters can also request an invitation be resent, or they can revoke an invitation. Unaccepted invitations expire after some time (such as 30 or 45 days).
Download OpenAPI Definition (YAML)
Base URLs:
Authentication
- API Key (
apiKey
)- header parameter: API-Key
- API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the
API-Key: {api-key}
request header.
- OAuth2 authentication (
accessToken
)- OAuth2 client access token authentication. The client authenticates against the server at
authorizationUrl
, passing the client's privateclientId
(and optionalclientSecret
) as part of this flow. The client obtains an access token from the server attokenUrl
. It then passes the received access token via theAuthorization: Bearer {access-token}
header in subsequent API calls. The authorization process also returns a refresh token which the client should use to renew the access token before it expires. - Flow:
authorizationCode
- Authorization URL = /auth/oauth2/authorize
- Token URL = /auth/oauth2/token
- OAuth2 client access token authentication. The client authenticates against the server at
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.
Try It
Example responses
200 Response
{
"id": "apiName",
"name": "API name",
"apiVersion": "1.0.0",
"_profile": "https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json",
"_links": {}
}
Responses
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.
Try It
Example responses
200 Response
{}
Responses
Status | Description |
---|---|
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. Default: 100 |
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 matches 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 matches 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 matches only items whose state is sent ; ?state=sent|accepted matches 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 matches only items whose type is joint ; ?state=joint|authorizedSigner matches 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 |
emailAddress (query) |
string Subset the invitations collection to those with this emailAddress value. Use | to separate multiple values. For example, ?emailAddress=johnsmith@email.com matches 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. |
Try It
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": {
"anyOf": [
{
"_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
Status | Description |
---|---|
200 | OK |
OK | |
Schema: invitations |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
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 = '{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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"
}';
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
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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"
}
Parameters
Parameter | Description |
---|---|
body (body) |
createInvitation (required) The data necessary to create a new invitation. |
Try It
Example responses
201 Response
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"_id": "string",
"state": "sent",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"customerId": "string",
"customerGroup": "string",
"verificationCount": 0,
"createdBy": "string"
}
Responses
Status | Description |
---|---|
201 | Created |
Created | |
Schema: invitation |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
409 | Conflict |
Conflict. Cannot create an invitation, possibly because joint owners are disabled or the account does not allow additional owners. Consult the _error object in the response for details. | |
Schema: errorResponse |
Response Headers
Status | Description |
---|---|
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. |
Try It
Example responses
200 Response
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"_id": "string",
"state": "sent",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"customerId": "string",
"customerGroup": "string",
"verificationCount": 0,
"createdBy": "string"
}
Responses
Status | Description |
---|---|
200 | OK |
OK | |
Schema: invitation |
Status | Description |
---|---|
304 | Not Modified |
Not Modified. The resource has not been modified since it was last fetched. |
Status | Description |
---|---|
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
Status | Description |
---|---|
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. |
Try It
Responses
Status | Description |
---|---|
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. |
Try It
Example responses
200 Response
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"_id": "string",
"state": "sent",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"customerId": "string",
"customerGroup": "string",
"verificationCount": 0,
"createdBy": "string"
}
Responses
Status | Description |
---|---|
200 | OK |
OK | |
Schema: invitation |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
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. |
Try It
Example responses
200 Response
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"_id": "string",
"state": "sent",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"customerId": "string",
"customerGroup": "string",
"verificationCount": 0,
"createdBy": "string"
}
Responses
Status | Description |
---|---|
200 | OK |
OK | |
Schema: invitation |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
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. |
Try It
Example responses
200 Response
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"_id": "string",
"state": "sent",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"customerId": "string",
"customerGroup": "string",
"verificationCount": 0,
"createdBy": "string"
}
Responses
Status | Description |
---|---|
200 | OK |
OK | |
Schema: invitation |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
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' \
-H 'Authorization: Bearer {access-token}'
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',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: '/invitations/verifications',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"sharedSecret": "obsolete obese octopus",
"invitationId": "d62c0701-0d74-4836-83f9-ebf3709442ea",
"_profile": "https://api.apiture.com/schemas/invitations/verification/v2.0.0/profile.json"
}';
const headers = {
'Content-Type':'application/hal+json',
'Accept':'application/hal+json',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
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',
'Authorization' => 'Bearer {access-token}'
}
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',
'Authorization': 'Bearer {access-token}'
}
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"},
"Authorization": []string{"Bearer {access-token}"},
}
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 in a state of sent
can be verified. sharedSecret
and invitationId
are required. This operation increases the verificationCount
of the invitation identified by invitationId
. Invitations that are revoked
or expired
are not processed. This operation does not verify invitations with a state of revoked
or expired
.
Body parameter
{
"sharedSecret": "obsolete obese octopus",
"invitationId": "d62c0701-0d74-4836-83f9-ebf3709442ea",
"_profile": "https://api.apiture.com/schemas/invitations/verification/v2.0.0/profile.json"
}
Parameters
Parameter | Description |
---|---|
body (body) |
verification (required) The data necessary to verify an invitation. |
Try It
Example responses
200 Response
{
"sharedSecret": "obsolete obese octopus",
"invitationId": "d62c0701-0d74-4836-83f9-ebf3709442ea",
"_profile": "https://api.apiture.com/schemas/invitations/verification/v2.0.0/profile.json"
}
Responses
Status | Description |
---|---|
200 | OK |
OK - the invitation was matched and accepted. | |
Schema: verification |
Status | Description |
---|---|
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 |
Status | Description |
---|---|
409 | Conflict |
Conflict. Only an invitation with a state of sent can be verified. Consult the _error object in the response for details. | |
Schema: errorResponse |
Status | Description |
---|---|
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
abstractRequest
{
"_profile": "{uri of resource profile.json}",
"_links": {
"self": {
"href": "{uri of current resource}"
}
}
}
Abstract Request (v2.0.0)
An abstract schema used to define other request-only schemas. This is a HAL resource representation, minus the _error
defined in abstractResource
.
Properties
Name | Description |
---|---|
_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 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. |
abstractResource
{
"_profile": "{uri of resource profile.json}",
"_links": {
"self": {
"href": "{uri of current resource}"
}
}
}
Abstract Resource (v2.0.0)
An abstract schema used to define other schemas for request and response bodies. This is a HAL resource representation. This model contains hypermedia _links
, and either optional domain object data with _profile
and optional _embedded
objects, or an _error
object. In responses, if the operation was successful, this object will not include the _error
, but if the operation was a 4xx or 5xx error, this object will not include _embedded
or any data fields, only _error
and optionally _links
.
Properties
Name | Description |
---|---|
_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 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. |
attributeValue
{}
Attribute Value (v2.0.0)
The data associated with this attribute.
Properties
attributes
{
"property1": {},
"property2": {}
}
Attributes (v2.0.0)
An optional map of name/value pairs which contains additional dynamic data about the resource.
Properties
Name | Description |
---|---|
additionalProperties | attributeValue The data associated with this attribute. |
collection
{
"_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": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"count": 0,
"start": 0,
"limit": 0,
"name": "string"
}
Collection (v2.0.0)
A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
Properties
Name | Description |
---|---|
_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 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. |
count | integer The number of items in the collection. This value is optional and may 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. |
createInvitation
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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"
}
Create Invitation
Representation used to create a new Invitation.
Properties
Name | Description |
---|---|
firstName | string The first name of the invitee. Warning: This property is deprecated and no longer used in invitation verification. |
lastName | string The lastName name of the invitee. Warning: This property is deprecated and no longer used in invitation verification. |
identification | string The last 4 digits of the government ID (SSN or other ID) of invitee. Warning: This property is deprecated and no longer used in invitation verification. |
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.
|
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.
|
role | string If type is authorizedSigner , this is the role of the invitee at the organization is being invited to.
|
inviterFullName | string (required) The full name of the user sending the invitation. |
_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 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
{
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
}
Error (v2.0.0)
Describes an error in an API request or in a service called via the API.
Properties
Name | Description |
---|---|
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. read-only
|
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.
|
errorResponse
{
"_profile": "https://api.apiture.com/schemas/common/errorResponse/v2.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 (v2.0.0)
Describes an error response, typically returned on 4xx or 5xx errors from API operations. The _error
object contains the error details.
Properties
Name | Description |
---|---|
_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 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. |
invitation
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string",
"_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": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"_id": "string",
"state": "sent",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"customerId": "string",
"customerGroup": "string",
"verificationCount": 0,
"createdBy": "string"
}
Invitation
Representation of invitation resources.
Properties
Name | Description |
---|---|
firstName | string The first name of the invitee. Warning: This property is deprecated and no longer used in invitation verification. |
lastName | string The lastName name of the invitee. Warning: This property is deprecated and no longer used in invitation verification. |
identification | string The last 4 digits of the government ID (SSN or other ID) of invitee. Warning: This property is deprecated and no longer used in invitation verification. |
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.
|
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.
|
role | string If type is authorizedSigner , this is the role of the invitee at the organization is being invited to.
|
inviterFullName | string The full name of the user sending the invitation. |
_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 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 organization resource. This is an immutable opaque string. read-only
|
state | string The derived state of invitation. read-only
|
createdAt | string(date-time) The date-time when the invitation was created. This is in RFC 3339format, UTC. This is derived and immutable. read-only
|
updatedAt | string(date-time) The date-time when the invitation was last updated. This is in RFC 3339format, UTC. This is derived and immutable. read-only
|
expiresAt | string(date-time) The date-time when the invitation will expire. This is in RFC 3339format, UTC. This is derived and immutable. read-only
|
customerId | string The derived core Customer Id of the person who created the Invitation. read-only
|
customerGroup | string The derived core Customer group of the person who created the Invitation. read-only
|
verificationCount | integer The derived count of attempted verifications of this invitation. read-only
|
createdBy | string The unique User Id of the person who created the Invitation. This is derived and immutable. read-only
|
invitationFields
{
"firstName": "string",
"lastName": "string",
"identification": "string",
"sharedSecret": "stringst",
"emailAddress": "string",
"type": "joint",
"accountUri": "string",
"organizationUri": "string",
"role": "string",
"inviterFullName": "string"
}
Invitation Fields
Representation of invitation resources.
Properties
Name | Description |
---|---|
firstName | string The first name of the invitee. Warning: This property is deprecated and no longer used in invitation verification. |
lastName | string The lastName name of the invitee. Warning: This property is deprecated and no longer used in invitation verification. |
identification | string The last 4 digits of the government ID (SSN or other ID) of invitee. Warning: This property is deprecated and no longer used in invitation verification. |
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.
|
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.
|
role | string If type is authorizedSigner , this is the role of the invitee at the organization is being invited to.
|
inviterFullName | string The full name of the user sending the invitation. |
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": {
"anyOf": [
{
"_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
Name | Description |
---|---|
_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. |
ยป 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 may 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. |
link
{
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
Link (v1.0.0)
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
Name | Description |
---|---|
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. |
links
{
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
}
Links (v1.0.0)
An optional map of links, mapping each link relation to a link object. This model defines the _links
object of HAL representations.
Properties
Name | Description |
---|---|
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.
|
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
Name | Description |
---|---|
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. |
root
{
"id": "apiName",
"name": "API name",
"apiVersion": "1.0.0",
"_profile": "https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json",
"_links": {}
}
API Root (v2.0.0)
A HAL response, with hypermedia _links
for the top-level resources and operations in API.
Properties
Name | Description |
---|---|
_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 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. read-only
|
name | string This API's name. |
apiVersion | string This API's version. |
verification
{
"sharedSecret": "obsolete obese octopus",
"invitationId": "d62c0701-0d74-4836-83f9-ebf3709442ea",
"_profile": "https://api.apiture.com/schemas/invitations/verification/v2.0.0/profile.json"
}
Verification
Representation of verification resources.
Properties
Name | Description |
---|---|
_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 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 The first name of the invitee. Warning: This property is deprecated and no longer used in invitation verification. |
lastName | string The lastName name of the invitee. Warning: This property is deprecated and no longer used in invitation verification. |
identification | string The last 4 digits of the government ID (SSN or other ID) of invitee. Warning: This property is deprecated and no longer used in invitation verification. |
sharedSecret | string (required) A string shared by the inviter with the invitee to verify their identity. minLength: 8
|
invitationId | string (required) A optional id of an invitation resource. If included, the service will compare the key data against this invitation only. |