Habit Logo
API docs by Redocly

Habit Distributor API (1.0)

Download OpenAPI specification:Download

E-mail: support@habit.io URL: https://www.habit.io

Habit Distributor API's allow insurance distributors to sell insurance products using Habit resources.

Accessing the API

In order to interact with the Habit API, clients must authenticate using the OAuth 2.0 protocol, in particular the Client credentials flow.

This call must be made using the /v3/auth/authorize endpoint, passing pre-generated\ncredentials, called client\_id and client\_secret.

Other required parameters are:

  • response_type, indicating the flow type, in this case client_credentials
  • scope, indicating the requested permissions, in this case manager or device
  • redirect_uri, in case the client needs to be redirect to a hosted callback
  • state, a value to be passed as part of the authorization result

The response will be populated with, at least, 4 main attributes:

  • access_token, the actual token to be used in subsequent calls
  • expires, the validity of the returned tokens
  • refresh_token, for refreshing this information, before expires is reached
  • endpoints, an object containing the HTTP and MQTT base URLs assigned to the requesting client

All subsequent calls must be directed to the base URL provided in endpoints.http and an Authorization header must be added to every API call, in the form of:

Authorization: Bearer {access_token}

Request parameters

PARAMETER TYPE DESCRIPTION
client_id uuid the client unique identifier, provided by the Habit self-care
client_secret string automatically generated hash, provide by the Habit self-care
redirect_uri uri URI to be provided to the user-agent as part of a 303 or 307 HTTP response
response_type string the OAuth 2.0 flow to be used
scope string a comma separated string of permissions to be associated with the token
state string a general purpose string that will be forwarded and added to the flow final result

Response fields

FIELD TYPE DESCRIPTION
access_token string the token to be used in subsequent calls to the API as part of an HTTP Authorization header
client_id uuid the client unique identifier
code string an exchange code, for usage with code flow requests
endpoints object HTTP and MQTT base URLs assigned to the requesting client
expires timestamp the expiration date for the provided tokens
grant_type string the type of grant flow used to generate the provided tokens
refresh_token string a token used with /v3/auth/exchange to retrieve fresh tokens, without the re-executing the entire flow
scope array granted permissions associated with the provided tokens
state string general purpose string forwarded by the client in the first flow call

Call using POST method

Request Body schema: application/json
client_id
required
string

Client ID from Selfcare

client_secret
required
string

Client Secret from Selfcare

response_type
required
string
scope
required
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "client_secret": "tqypzi6q3faldgbrtyhbh6e2",
  • "response_type": "client_credentials",
  • "scope": "distributor"
}

Response samples

Content type
application/json
{
  • "access_token": "{access_token}",
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "code": "{code}",
  • "endpoints": {},
  • "expires": "2020-12-31T00:00:00.000+0000",
  • "grant_type": "client_credentials",
  • "refresh_token": "{refresh_token}",
  • "scope": [
    ]
}

Call using GET method

query Parameters
client_id
required
string
Example: client_id=bef41164-90c6-11e7-a25d-97266664a105
client_secret
required
string
Example: client_secret=tqypzi6q3faldgbrtyhbh6e2
response_type
required
string
Example: response_type=client_credentials
scope
required
string
Example: scope=distributor
redirect_uri
string
state
string
header Parameters
Content-Type
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "access_token": "{access_token}",
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "code": "{code}",
  • "endpoints": {},
  • "expires": "2020-12-31T00:00:00.000+0000",
  • "grant_type": "client_credentials",
  • "refresh_token": "{refresh_token}",
  • "scope": [
    ]
}

Renew token

Before the expiration timestamp returns as expired, the client should renew the access token by calling the /v3/auth/exchange endpoint, passing the refresh_token return with the call to /v3/auth/authorize.

The return will be exactly the same as the return by /v3/auth/authorize.

Request parameters

PARAMETER TYPE DESCRIPTION
client_id uuid the client unique identifier, provided by the Habit self-care
redirect_uri uri URI to be provided to the user-agent as part of a 303 or 307 HTTP response
refresh_token string the token provided as refresh_token in a previous call to /v3/auth/authorize
grant_type string the type of grant flow used to generate the provided tokens

Response fields

FIELD TYPE DESCRIPTION
access_token string the token to be used in subsequent calls to the API as part of an HTTP Authorization header
client_id uuid the client unique identifier
code string an exchange code, for usage with code flow requests
endpoints object HTTP and MQTT base URLs assigned to the requesting client
expires timestamp the expiration date for the provided tokens
grant_type string the type of grant flow used to generate the provided tokens
refresh_token string a token used with /v3/auth/exchange to retrieve fresh tokens, without executing the entire flow
scope array granted permissions associated with the provided tokens

Call using POST method

Request Body schema: application/json
client_id
required
string
refresh_token
required
string
grant_type
required
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "refresh_token": "{refresh_token}",
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "{access_token}",
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "code": "{code}",
  • "endpoints": {},
  • "expires": "2020-12-31T00:00:00.000+0000",
  • "grant_type": "client_credentials",
  • "refresh_token": "{refresh_token}",
  • "scope": [
    ]
}

Call using GET method

query Parameters
client_id
required
string
Example: client_id=bef41164-90c6-11e7-a25d-97266664a105
refresh_token
required
string
Example: refresh_token={refresh_token}
grant_type
required
string
Example: grant_type=client_credentials
redirect_uri
string
header Parameters
Content-Type
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "access_token": "{access_token}",
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "code": "{code}",
  • "endpoints": {},
  • "expires": "2020-12-31T00:00:00.000+0000",
  • "grant_type": "client_credentials",
  • "refresh_token": "{refresh_token}",
  • "scope": [
    ]
}

Insurance Products

Single Product

Use the following method to retrieve insurance products being sold

Response fields

FIELD TYPE DESCRIPTION
id uuid Insurance Product unique identifier
name string Insurance Product Name
icon string (uri) icon uri
image string (uri) image uri
state string Insurance Product state
namespace string Insurance Product namespace
type string Insurance Product type
created string (date) creation date
updated string (date) update date
active_ts string (date) activation date
inactive_ts string (date) inactivation date
legal_disclaimers array Legal disclaimers to use with that product
cdata json Object with extra informations about the product like country
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "id": "0cc9de4b-1b70-406d-b67b-766cf9c53cca",
  • "name": "insurance product",
  • "icon": "icon_uri",
  • "image": "image_uri",
  • "state": "active",
  • "namespace": "insurance_namespace",
  • "type": ":type",
  • "created": "2020-08-27T00:00:00.000+0000",
  • "updated": "2020-08-27T00:00:00.000+0000",
  • "active_ts": "2020-08-27T00:00:00.000+0000",
  • "inactive_ts": "2020-08-27T00:00:00.000+0000",
  • "legal_disclaimers": [
    ],
  • "cdata": {
    },
  • "documents": {
    }
}

All products

Use the following method to retrieve an array of insurance products being sold.

Response fields

FIELD TYPE DESCRIPTION
elements array Array of insurance products being sold
size number Number of insurance products in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Insurance Product unique identifier
name string Insurance Product Name
icon string (uri) icon uri
image string (uri) image uri
state string Insurance Product state
namespace string Insurance Product namespace
type string Insurance Product type
created string (date) creation date
updated string (date) update date
active_ts string (date) activation date
inactive_ts string (date) inactivation date
legal_disclaimers array Legal disclaimers to use with that product
cdata json Object with extra informations about the product like country
Authorizations:
OAuth2 Authorization
query Parameters
id
string <uuid>

entity id to filter by.

name
string

complete entity name to filter by.

namespace
string

complete entity namespace to filter by.

state
string

complete entity state to filter by.

page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Coverages

All Coverages

Use the following method to retrieve an array of coverage specs that will be linked to the quote when quote is submitted.

Response fields

FIELD TYPE DESCRIPTION
elements array Array of coverage specs
size number Number of coverage specs in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Quote Coverage Spec unique identifier
coverage_id uuid Coverage unique identifier
quotespec_id uuid Quote spec unique identifier
namespace string Namespace of the Coverage
order_index string Coverage order index
classes array Array of classes linked to the Coverage
created string (date) creation date
updated string (date) update date
properties array Array with all coverage properties
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

version_id
required
string <uuid>
Example: 58970c9d-7c6c-4b4e-9664-ec3001899ca0

The ID of the desired version.

query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

namespace
string

complete entity namespace to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Single Coverages

Retrieve information about coverage specs that will be linked to the quote when quote is submitted.

Response fields

FIELD TYPE DESCRIPTION
id uuid Quote Coverage Spec unique identifier
coverage_id uuid Coverage unique identifier
quotespec_id uuid Quote spec unique identifier
namespace string Namespace of the Coverage
order_index string Coverage order index
classes array Array of classes linked to the Coverage
created string (date) creation date
updated string (date) update date
properties array Array with all coverage properties
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

version_id
required
string <uuid>
Example: 58970c9d-7c6c-4b4e-9664-ec3001899ca0

The ID of the desired version.

coverage_id
required
string <uuid>
Example: b05924ae-f7b6-47dd-a074-3f51ae290459

The ID of the coverage.

query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

namespace
string

complete entity namespace to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "id": "b05924ae-f7b6-47dd-a074-3f51ae290459",
  • "coverage_id": "08a166a0-e29b-47c2-ab2b-a73b0987ccd8",
  • "quotespec_id": "ee0c8f10-0b90-415c-947f-b5d8271d647a",
  • "namespace": "family_protection",
  • "order_index": 0,
  • "classes": [
    ],
  • "properties": [
    ]
}

Users

All Users

Use the following method to retrieve an array of users linked to the distributors and the insurance product

Response fields

FIELD TYPE DESCRIPTION
elements array Array of users
size number Number of users in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid User unique identifier
name string User's name
email string User's e-mail
mobile string User's mobile number
active_ts string (date) Date when user got active
inactive_ts string (date) Date when user got inactive
created string (date) Date when user was created
updated string (date) Date when user was updated
target_id uuid ID of insurance-product linked to the user
partner_code string Distributor custom code linked to the user
flags string Distributor custom flags linked to the user
state string Actual user state
type string user client type
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

name
string

complete entity name to filter by.

email
string

complete entity email to filter by.

state
string

complete entity state to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Create User

create users linked to the distributors and the Insurance Product

Request fields

FIELD TYPE DESCRIPTION
name string User's name
email string User's e-mail
mobile string User's mobile number with international code
partner_code string (optional) Distributor custom code
flags object (optional) Distributor custom flags

Response fields

FIELD TYPE DESCRIPTION
id uuid User unique identifier
name string User's name
email string User's e-mail
mobile string User's mobile number
active_ts string (date) Date when user became active
inactive_ts string (date) Date when user became inactive
created string (date) Date when user was created
updated string (date) Date when user was updated
target_id uuid ID of insurance-product linked to the user
partner_code string Distributor custom code linked to the user
flags string Distributor custom flags linked to the user
state string Actual user state
type string user client type
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
name
required
string

User name to be created

email
required
string

User email

mobile
string

User mobile number with international code

partner_code
string

Distributor custom code to be linked to the user

flags
string

Distributor custom flags to be linked to the user

Responses

Request samples

Content type
application/json
{
  • "name": "New User",
  • "email": "new.user@habit.io",
  • "mobile": "+999999999999",
  • "partner_code": "XYZ1234",
  • "flags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "3bfb32f9-7a48-4d89-894e-d4ba49f7df2e",
  • "name": "New User",
  • "email": "new.user@habit.io",
  • "mobile": "+999999999999",
  • "active_ts": "2020-09-18T14:15:56.095+0000",
  • "inactive_ts": "2020-09-18T14:15:56.095+0000",
  • "created": "2020-09-18T14:15:56.095+0000",
  • "updated": "2020-09-18T14:15:56.095+0000",
  • "target_id": "0cc9de4b-1b70-406d-b67b-766cf9c53cca",
  • "partner_code": "XYZ1234",
  • "flags": {
    },
  • "state": "active",
  • "type": "user"
}

Single User

Retrieve single user information

Response fields

FIELD TYPE DESCRIPTION
id uuid User unique identifier
name string User's name
email string User's e-mail
mobile string User's mobile number
active_ts string (date) Date when user became active
inactive_ts string (date) Date when user became inactive
created string (date) Date when user was created
updated string (date) Date when user was updated
target_id uuid ID of insurance-product linked to the user
partner_code string Distributor custom code linked to the user
flags string Distributor custom flags linked to the user
state string Actual user state
type string user client type
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

user_id
required
string <uuid>
Example: 3bfb32f9-7a48-4d89-894e-d4ba49f7df2e

The ID of the desired user.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "id": "3bfb32f9-7a48-4d89-894e-d4ba49f7df2e",
  • "name": "New User",
  • "email": "new.user@habit.io",
  • "mobile": "+999999999999",
  • "active_ts": "2020-09-18T14:15:56.095+0000",
  • "inactive_ts": "2020-09-18T14:15:56.095+0000",
  • "created": "2020-09-18T14:15:56.095+0000",
  • "updated": "2020-09-18T14:15:56.095+0000",
  • "target_id": "0cc9de4b-1b70-406d-b67b-766cf9c53cca",
  • "partner_code": "XYZ1234",
  • "flags": {
    },
  • "state": "active",
  • "type": "user"
}

Update User

Update User's Information

Request fields

FIELD TYPE DESCRIPTION
name string (optional) User's name
email string (optional) User's e-mail
mobile string (optional) User's mobile number with international code
partner_code string (optional) Distributor custom code
flags object (optional) Distributor custom flags

Response fields

FIELD TYPE DESCRIPTION
n_updated number Number of quote properties updated
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

user_id
required
string <uuid>
Example: 3bfb32f9-7a48-4d89-894e-d4ba49f7df2e

The ID of the desired user.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
name
string

User name to be created

email
string

User email

mobile
string

User mobile number with international code

partner_code
string

Distributor custom code to be linked to the user

flags
string

Distributor custom flags to be linked to the user

Responses

Request samples

Content type
application/json
{
  • "name": "New User",
  • "email": "new.user@habit.io",
  • "mobile": "+999999999999",
  • "partner_code": "XYZ1234",
  • "flags": {
    }
}

Response samples

Content type
application/json
{
  • "n_updated": 1
}

Quotes

Get quote spec by insurance product

Use the following method to retrieve all necessary properties to create a quote.

Response fields

FIELD TYPE DESCRIPTION
insuranceproduct_id uuid Insurance Product unique identifier
quote_specs array Array with all available quote properties
policyholder_specs array Array with all available policy holder properties
protectedasset_specs array Array with all available protected asset properties
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

version_id
required
string <uuid>
Example: 58970c9d-7c6c-4b4e-9664-ec3001899ca0

The ID of the desired version.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "client_id": "0cc9de4b-1b70-406d-b67b-766cf9c53cca",
  • "service_id": "11539368-524f-4b79-8902-28e1935fdf8e",
  • "service": { },
  • "specs": {
    }
}

Submit a quote for an insurance product by ID

Use the following method to submit a new quote to the insurance company

Request fields

FIELD TYPE DESCRIPTION
quote_properties array Array with all quote properties to be created (properties id or namespace can be used)
policyholder_properties array Array with all policy holder properties to be created (this field will be ignored if you set "policyholder_id" field)
protectedasset_properties array Array with all protected asset properties to be created
coverages array Array with all coverages to be created/changed
user_id uuid User unique identifier to be linked with created quote
policyholder_id uuid Policy Holder unique identifier to be linked with the created quote (if you set this field, we will ignore the "policyholder_properties" field. To be able to reuse the session you must set the "user_id" field or "session_fingerprint" field from the last quote response that created the policyholder)

Response fields

FIELD TYPE DESCRIPTION
created object Object with created Quote
customized object Object with all quote properties updated in the setup process by Insurer
simulated object Object with all quote properties updated in the simulation process by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

version_id
required
string <uuid>
Example: 58970c9d-7c6c-4b4e-9664-ec3001899ca0

The ID of the desired version.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
session_fingerprint
string
user_id
string
Array of objects (quoteSpecPropNamespace)
Array of objects (policyHolderSpecNamespace)
policyholder_id
string
Array of objects (protectedAssetSpecNamespace)
Array of objects (coverage)

Responses

Request samples

Content type
{
  • "session_fingerprint": "2ec8ea29-ee45-4ee5-a7e3-bf04a156d4ae-2ec8ea29-ee45-4ee5-a7e3-bf04a156d4ae-anon-2ec8ea29-ee45-4ee5-a7e3-bf04a156d4ae",
  • "user_id": "2ec8ea29-ee45-4ee5-a7e3-bf04a156d4ae",
  • "quote_properties": [
    ],
  • "policyholder_properties": [
    ],
  • "policyholder_id": "1cc8ea29-ee45-4ee5-a7e3-bf04a156d4ae",
  • "protectedasset_properties": [
    ],
  • "coverages": [
    ]
}

Response samples

Content type
application/json
{
  • "created": {
    },
  • "customized": {
    },
  • "simulated": {
    }
}

All quotes

After a successfully simulation it becomes a simulated quote. Use the following method to retrieve an array of submitted quotes.

Response fields

FIELD TYPE DESCRIPTION
elements array Array of submitted quotes
size number Number of submitted quotes in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Quote unique identifier
code string Internal code to identify the quote
state string Actual quote state (draft, open, simulated, processing, error, closed or canceled)
session_id uuid ID of the session used to create the quote
user_id uuid ID of the user linked to the quote
classes array Array of classes linked to the quote
open_ts string (date) Date when quote was sent to open state
simulated_ts string (date) Date when quote was sent to simulated state
processing_ts string (date) Date when quote was sent to processing state
error_ts string (date) Date when quote was sent to error state
closed_ts string (date) Date when quote was sent to closed state
canceled_ts string (date) Date when quote was sent to canceled state
service_id uuid ID of the service related to the quote
service object Service details
policy_id uuid ID of the Policy created from this quote
reason string reason for quote approval or rejection
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

user_id
string <uuid>

user id to filter by.

state
string

complete entity state to filter by.

namespace
string

complete entity namespace to filter by.

code
string

complete entity code to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Single Quote

After a quote is successfully simulated it becomes a simulated quote. Use the following method to retrieve quote.

Response fields

FIELD TYPE DESCRIPTION
id uuid Quote unique identifier
code string Internal code to identify the quote
state string Actual quote state (draft, open, simulated, processing, error, closed or canceled)
session_id uuid ID of the session used to create the quote
user_id uuid ID of the user linked to the quote
classes array Array of classes linked to the quote
open_ts string (date) Date when quote was sent to open state
simulated_ts string (date) Date when quote was sent to simulated state
processing_ts string (date) Date when quote was sent to processing state
error_ts string (date) Date when quote was sent to error state
closed_ts string (date) Date when quote was sent to closed state
canceled_ts string (date) Date when quote was sent to canceled state
service_id uuid ID of the service related to the quote
service object Service details
policy_id uuid ID of the Policy created from this quote
reason string reason for quote approval or rejection
coverages array Array with quote's coverages
policy_holders array Array with quote's policy holders
protectedassets array Array with quote's protected assets
assets array Array with quote's assets
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "id": "1ea47dd4-6c9c-4b05-8575-549e04cfee81",
  • "code": "ABC123",
  • "session_id": "14990e13-1663-48e5-b14f-362c463dad84",
  • "user_id": "2ec8ea29-ee45-4ee5-a7e3-bf04a156d4ae",
  • "classes": [
    ],
  • "created": "2020-08-27T00:00:00.000+0000",
  • "updated": "2020-08-27T00:00:00.000+0000",
  • "open_ts": "2020-08-27T00:00:00.000+0000",
  • "simulated_ts": "2020-08-27T00:00:00.000+0000",
  • "processing_ts": "2020-08-27T00:00:00.000+0000",
  • "error_ts": "2020-08-27T00:00:00.000+0000",
  • "closed_ts": "2020-08-27T00:00:00.000+0000",
  • "canceled_ts": "2020-08-27T00:00:00.000+0000",
  • "service_id": "11539368-524f-4b79-8902-28e1935fdf8e",
  • "service": { },
  • "state": "open",
  • "properties": [
    ],
  • "policy_id": "string",
  • "reason": "string",
  • "coverages": [
    ],
  • "protectedassets": [
    ],
  • "policy_holders": [
    ],
  • "files": []
}

Update quote properties

Add or update quote details

Requirements:

  • To create/update Quote's properties, it cannot have been converted to a policy

Request fields

FIELD TYPE DESCRIPTION
properties array Array with all quote properties to be created or updated (properties id or namespace can be used)

Each property must contain the following information

Request Properties

FIELD TYPE DESCRIPTION
quotepropertyspec_id uuid Quote Property Spec unique identifier to be created or updated. Either this or namespace must be specified.
namespace string Quote Property Spec namespace to be created or updated. Either this or quotepropertyspec_id must be specified.
data string (required) Data to be set in property

Response fields

FIELD TYPE DESCRIPTION
properties array Array with all created or updated properties
n_updated number Number of quote properties updated
simulated object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
Array of objects (quoteSpecPropNamespace)

Responses

Request samples

Content type
{
  • "properties": [
    ]
}

Response samples

Content type
application/json
{
  • "properties": [
    ],
  • "n_updated": 1,
  • "simulated": {
    }
}

Update quote coverages

Add or update quote coverages

Requirements:

  • To create/update Quote's coverages and properties

Request fields

FIELD TYPE DESCRIPTION
coverages array Array with all coverages to be created/changed

Each coverage must contain the following information

Request Coverages

FIELD TYPE DESCRIPTION
coverage_id uuid Quote Coverage ID unique identifier to be created or updated. Either this or namespace must be specified.
namespace string Quote Coverage Spec namespace to be created or updated. Either this or coverage_id must be specified.
properties array (optional) Data to be set in property

Each property must contain the following information

Request Properties

FIELD TYPE DESCRIPTION
quotecoveragepropertyspec_id uuid Quote Coverage Property Spec unique identifier to be created or updated. Either this or namespace must be specified.
namespace string Quote Coverage Property Spec namespace to be created or updated. Either this or quotecoveragepropertyspec_id must be specified.
data string (required) Data to be set in property

Response fields

FIELD TYPE DESCRIPTION
coverages array Array with all coverages
n_created number Number of quote coverage properties created
n_updated number Number of quote coverage properties updated
simulated object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
Array of objects (coverage)

Responses

Request samples

Content type
{
  • "coverages": [
    ]
}

Response samples

Content type
application/json
{
  • "coverages": [
    ],
  • "n_updated": 1,
  • "simulated": {
    }
}

Delete quote coverages

delete quote coverages

Requirements:

  • To delete Quote's coverages

Request fields

FIELD TYPE DESCRIPTION
coverages array Array with all coverages to be created/changed

Each coverage must contain the following information

Request Coverages

FIELD TYPE DESCRIPTION
coverage_id uuid Quote Coverage ID unique identifier to be deleted. Either this or namespace must be specified.
namespace string Quote Coverage Spec namespace to be deleted. Either this or coverage_id must be specified.

Response fields

FIELD TYPE DESCRIPTION
n_deleted number Number of quote coverage removed
simulated object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
Array of objects (coverage)

Responses

Request samples

Content type
{
  • "coverages": [
    ]
}

Response samples

Content type
application/json
{
  • "n_deleted": 1,
  • "simulated": {
    }
}

Attach files to a quote

Attach files to a quote. A file can be a document, picture, video, audio or json. Use classes to properly identify file type.

Request fields

FIELD TYPE DESCRIPTION
files array Array with all files to be attached

Each asset must contain the following information

Request assets

FIELD TYPE DESCRIPTION
name string Filename from file-upload result
uri url File url from file-upload result
icon url (optional) File icon from file-upload result
image url (optional) File image from file-upload result
classes array (optional) Array of classes to be attached to the file. Find bellow available classes

Response fields

FIELD TYPE DESCRIPTION
files array Array with all attached files

Avaliable Asset Classes

TYPE DESCRIPTION
io.habit.trackableassets.type.document Documents (*.pdf)
io.habit.trackableassets.type.photo Images (*.png, *.jpg)
io.habit.trackableassets.type.video Videos (*.mp4)
io.habit.trackableassets.type.json Json
io.habit.trackableassets.type.audio Audio
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
Array of objects (attachFiles)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Create a Protected Asset and link to a Quote

Create a new Protected Asset and link with an existent and active quote

Requirements:

  • Quote state can't be closed, states can be draft, open, simulated

Request fields

FIELD TYPE DESCRIPTION
protectedasset_properties array Array with all protected asset properties to be created

Response fields

FIELD TYPE DESCRIPTION
created object Object with created Protected Asset
customized object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
Array of objects (protectedAssetSpecPropNamespace)

Responses

Request samples

Content type
{
  • "protectedasset_properties": [
    ]
}

Response samples

Content type
application/json
{
  • "href": "/v3/data-layer/quote-protected-assets/f3ec5688-709f-4c94-94dc-88897c9a2e20",
  • "id": "f3ec5688-709f-4c94-94dc-88897c9a2e20",
  • "customized": {
    }
}

Delete a Protected Assets linked to a quote

Delete Protected Assets linked to a quote

Requirements:

  • Quote state can't be closed, states can be draft, open, simulated

Request fields

FIELD TYPE DESCRIPTION
protectedassets array Array with all protected asset ids to be deleted

Request protected assets

FIELD TYPE DESCRIPTION
protectedasset_id uuid Protected Asset ID unique identifier to be deleted.

Response fields

FIELD TYPE DESCRIPTION
n_deleted number Number of protected assets deleted
simulated object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
Array of objects (PADelete)

Responses

Request samples

Content type
application/json
{
  • "protectedassets": [
    ]
}

Response samples

Content type
application/json
{
  • "n_deleted": 1,
  • "simulated": {
    }
}

Policy Holders

Create Policy holder and link to a quote

Create a new policy holder and associate with a quote

If user is present, the API will try to create a new user, or find an existing one with data sent. This user will be linked to the Policy Holder and Quote

Request fields

FIELD TYPE DESCRIPTION
quote_id uuid, required Quote unique identifier
user_id uuid User unique identifier to be linked with policy holder
version_id string, optional Specs version to be used when creating the policy holder.
properties array Array with all policy holder properties to be created

A list of available properties can be retrieved using Quotes -> Retrieve Specs method

Response fields

  • Policy holder fields

    FIELD TYPE DESCRIPTION
    id uuid Policy Holder unique identifier
    code string Internal code to identify the Policy Holder
    state string Actual Policy Holder state default: draft
    session_id uuid ID of the session used to create the Policy Holder
    user_id uuid ID of the user linked to the Policy Holder
    classes array Array of classes linked to the Policy Holder
    namespace string Namespace of the Policy Holder
    parent_id uuid Parent Policy Holder unique identifier
    quotes array Array of quotes linked to the Policy Holder
    properties array Array of Policy Holder's properties. Retrieved only for a single Policy Holder

  • Extra fields:

    FIELD TYPE DESCRIPTION
    simulated object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
quote_id
required
string
user_id
string
version_id
string
Array of objects (Policy Holder Property Create Id)

Responses

Request samples

Content type
{
  • "quote_id": "1ea47dd4-6c9c-4b05-8575-549e04cfee81",
  • "user_id": "2ec8ea29-ee45-4ee5-a7e3-bf04a156d4ae",
  • "version_id": "58970c9d-7c6c-4b4e-9664-ec3001899ca0",
  • "properties": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "7742945f-8bc9-4e7d-91b4-9c8298696427",
  • "quote": {
    },
  • "namespace": "string",
  • "code": "ABC456",
  • "session_id": "string",
  • "user_id": "string",
  • "parent_id": "string",
  • "classes": [
    ],
  • "state": "draft",
  • "properties": [
    ],
  • "simulated": {
    }
}

Single Policy Holder

Retrieve information about policy holders

Response fields

FIELD TYPE DESCRIPTION
id uuid Policy Holder unique identifier
code string Internal code to identify the Policy Holder
state string Actual Policy Holder state default: draft
session_id uuid ID of the session used to create the Policy Holder
user_id uuid ID of the user linked to the Policy Holder
classes array Array of classes linked to the Policy Holder
namespace string Namespace of the Policy Holder
parent_id uuid Parent Policy Holder unique identifier
quotes array Array of quotes linked to the Policy Holder
properties array Array of Policy Holder's properties. Retrieved only for a single Policy Holder
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policyholder_id
required
string <uuid>
Example: 7742945f-8bc9-4e7d-91b4-9c8298696427

The ID of the desired policy-holder.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "id": "7742945f-8bc9-4e7d-91b4-9c8298696427",
  • "quotes": [
    ],
  • "namespace": "string",
  • "code": "ABC456",
  • "session_id": "string",
  • "user_id": "string",
  • "parent_id": "string",
  • "classes": [
    ],
  • "state": "draft",
  • "properties": [
    ]
}

All Policy Holders

Use the following method to retrieve an array of created policy holders

Response fields

FIELD TYPE DESCRIPTION
elements array Array of policy holders
size number Number of policy holders in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Policy Holder unique identifier
code string Internal code to identify the Policy Holder
state string Actual Policy Holder state default: draft
session_id uuid ID of the session used to create the Policy Holder
user_id uuid ID of the user linked to the Policy Holder
classes array Array of classes linked to the Policy Holder
namespace string Namespace of the Policy Holder
parent_id uuid Parent Policy Holder unique identifier
quotes array Array of quotes linked to the Policy Holder
properties array Array of Policy Holder's properties. Retrieved only for a single Policy Holder
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

code
string

complete entity code to filter by.

state
string

complete entity state to filter by.

namespace
string

complete entity namespace to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Update Policy Holder's properties

Update Policy Holder's properties according to payload

Request fields

FIELD TYPE DESCRIPTION
properties array Array with all policy holder properties to be updated
quote_id uuid Quote unique identifier (optional)

Each property must contain the following information

Request Properties

FIELD TYPE DESCRIPTION
policyholderpropertyspec_id uuid Policy Holder Property Spec unique identifier to be created or updated. Either this or namespace must be specified.
namespace string Policy Holder Property Spec namespace to be created or updated. Either this or policyholderpropertyspec_id must be specified.
data string (required) Data to be set in property

Response fields

FIELD TYPE DESCRIPTION
properties array Array with all created or updated properties
n_updated number Number of quote properties updated
simulated object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policyholder_id
required
string <uuid>
Example: 7742945f-8bc9-4e7d-91b4-9c8298696427

The ID of the desired policy-holder.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
required
Array of objects (Policy Holder Property Create Namespace)
quote_id
string

Responses

Request samples

Content type
{
  • "properties": [
    ],
  • "quote_id": "1ea47dd4-6c9c-4b05-8575-549e04cfee81"
}

Response samples

Content type
application/json
{
  • "properties": [
    ],
  • "n_updated": 1,
  • "simulated": {
    }
}

Protected Assets

Single Protected Asset

Retrieve information about Protected Assets

Response fields

FIELD TYPE DESCRIPTION
id uuid Protected Asset unique identifier
namespace string Namespace of the Protected Asset
quote_id uuid Quote unique identifier
quote object Object with quote's details
classes array Array of classes linked to the Protected Asset
parent_id uuid Parent Protected Asset unique identifier
properties array Array with all protected asset properties
assets array Array with protected asset's assets
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

protectedasset_id
required
string <uuid>
Example: f3ec5688-709f-4c94-94dc-88897c9a2e20

The ID of the desired protected asset.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "id": "f3ec5688-709f-4c94-94dc-88897c9a2e20",
  • "namespace": "string",
  • "quote_id": "1ea47dd4-6c9c-4b05-8575-549e04cfee81",
  • "quote": {
    },
  • "parent_id": "string",
  • "classes": [
    ],
  • "properties": [
    ],
  • "files": []
}

All Protected Assets

Use the following method to retrieve an array of Protected Assets.

Response fields

FIELD TYPE DESCRIPTION
elements array Array of Protected Assets
size number Number of Protected Assets in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Protected Asset unique identifier
namespace string Namespace of the Protected Asset
quote_id uuid Quote unique identifier
quote object Object with quote's details
classes array Array of classes linked to the Protected Asset
parent_id uuid Parent Protected Asset unique identifier
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

namespace
string

complete entity namespace to filter by.

quote_id
string <uuid>

quote id to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Retrieve protected asset property specs

Retrieve all available protected asset specs to update protected asset properties

Response fields

FIELD TYPE DESCRIPTION
elements array Array with all available protected asset properties
size number Number of properties in elements
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

version_id
required
string <uuid>
Example: 58970c9d-7c6c-4b4e-9664-ec3001899ca0

The ID of the desired version.

query Parameters
id
string <uuid>

entity id to filter by.

namespace
string

complete entity namespace to filter by.

label
string

complete entity label to filter by.

force_data
boolean

boolean indicating force_data state to filter by.

schema
string

complete entity schema to filter by.

order_index
number <integer>

entity order_index to filter by.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Update Protected Asset's properties

Add or Update additional information about a protected asset. A list of available properties can be retrieved using Protected Asset -> Protected Asset Property Specs method

Request fields

FIELD TYPE DESCRIPTION
properties array Array with all protected asset properties to be created or updated

Each property must contain the following information

Request Properties

FIELD TYPE DESCRIPTION
protectedassetpropertyspec_id uuid (required) Protected Asset Property Spec unique identifier to be created or updated. Either this or namespace must be specified.
namespace uuid (required) Protected Asset Property Spec namespace to be created or updated. Either this or protectedassetpropertyspec_id must be specified.
data string (required) Data to be set in property

Response fields

FIELD TYPE DESCRIPTION
properties array Array with all created or updated properties
n_updated number Number of protected asset properties updated
simulated object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

protectedasset_id
required
string <uuid>
Example: f3ec5688-709f-4c94-94dc-88897c9a2e20

The ID of the desired protected asset.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
Array of objects (protectedAssetSpecPropNamespace)

Responses

Request samples

Content type
{
  • "properties": [
    ]
}

Response samples

Content type
application/json
{
  • "properties": [
    ],
  • "n_updated": 1,
  • "simulated": {
    }
}

Attach files to a Protected Asset

Attach files to a Protected Asset. A file can be a document, picture, video, audio or json. Use classes to properly identify file type.

Request fields

FIELD TYPE DESCRIPTION
files array Array with all files to be attached

Each asset must contain the following information

Request assets

FIELD TYPE DESCRIPTION
name string Filename from file-upload result
uri url File url from file-upload result
icon url (optional) File icon from file-upload result
image url (optional) File image from file-upload result
classes array (optional) Array of classes to be attached to the file. Find bellow available classes

Response fields

FIELD TYPE DESCRIPTION
files array Array with all attached files

Avaliable Asset Classes

TYPE DESCRIPTION
io.habit.trackableassets.type.document Documents (*.pdf)
io.habit.trackableassets.type.photo Images (*.png, *.jpg)
io.habit.trackableassets.type.video Videos (*.mp4)
io.habit.trackableassets.type.json Json
io.habit.trackableassets.type.audio Audio
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

protectedasset_id
required
string <uuid>
Example: f3ec5688-709f-4c94-94dc-88897c9a2e20

The ID of the desired protected asset.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
Array of objects (attachFiles)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Contracts

Submit a contract

Create a contract for a simulated quote

User information is required to create a contract. If the user exists you can send user_id in request payload, or you can send all user information to be created inside user request payload

If both parameters were sent, user parameter will be ignored and policy will be linked to the user_id

Requirements:

  • Quote state must be equal to simulated

Request fields

FIELD TYPE DESCRIPTION
user_id uuid User unique identifier to be linked with a contract
user object User information to be created and linked to the quote and policy

Response fields

  • Policy Fields:

    FIELD TYPE DESCRIPTION
    id uuid Policy unique identifier
    code string Internal code to identify the Policy
    state string Actual quote state (active, inactive, suspend, canceled, renewed)
    created string (date) Policy instance creation date
    updated string (date) Policy instance last update date
    active_ts string (date) Policy last activation date
    inactive_ts string (date) Policy last inactivation date
    suspended_ts string (date) Policy last suspension date
    canceled_ts string (date) Policy cacelation date
    renewed_ts string (date) Policy renovation date
    user_id string ID of the user linked to the policy
    quote_id uuid Quote unique identifier
    quote object Object with quote's details

  • Extra fields:

    FIELD TYPE DESCRIPTION
    customized object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
user_id
string

User unique identifier to be linked with a contract

object (userCreateRequest)

Responses

Request samples

Content type
application/json
{
  • "user_id": "3bfb32f9-7a48-4d89-894e-d4ba49f7df2e",
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "id": "bb6e1769-5685-4fc8-b9f5-f29a9ac6771e",
  • "code": "ABC789",
  • "state": "active",
  • "custom_state": "string",
  • "user_id": "string",
  • "quote_id": "1ea47dd4-6c9c-4b05-8575-549e04cfee81",
  • "quote": {
    },
  • "reason_id": "io.habit.policies.other",
  • "created": "2020-08-27T00:00:00.000+0000",
  • "updated": "2020-08-27T00:00:00.000+0000",
  • "active_ts": "2020-08-27T00:00:00.000+0000",
  • "inactive_ts": "2020-08-27T00:00:00.000+0000",
  • "suspended_ts": "2020-08-27T00:00:00.000+0000",
  • "canceled_ts": "2020-08-27T00:00:00.000+0000",
  • "renewed_ts": "2020-08-27T00:00:00.000+0000",
  • "files": [],
  • "coverages": [
    ],
  • "customized": {
    }
}

Policies

Single Policy

After a contract is approved by the insurance company, it becomes a Policy.

Use the following method to retrieve information about Policies

Response fields

FIELD TYPE DESCRIPTION
id uuid Policy unique identifier
code string Internal code to identify the Policy
state string Actual quote state (active, inactive, suspend, canceled, renewed)
custom_state string Custom state for the contract (active, inactive, suspended, canceled, renewed)
user_id string ID of the user linked to the policy
quote_id uuid Quote unique identifier
quote object Object with quote's details
reason_id string Reason to explain policy state or custom_state
classes array Array of classes linked to the Protected Asset
created string (date) Policy instance creation date
updated string (date) Policy instance last update date
active_ts string (date) Policy last activation date
inactive_ts string (date) Policy last inactivation date
suspended_ts string (date) Policy last suspension date
canceled_ts string (date) Policy cacelation date
renewed_ts string (date) Policy renovation date
files array Array of files linked to the Policy
coverages array Array with policy's coverages
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "id": "bb6e1769-5685-4fc8-b9f5-f29a9ac6771e",
  • "code": "ABC789",
  • "state": "active",
  • "custom_state": "string",
  • "user_id": "string",
  • "quote_id": "1ea47dd4-6c9c-4b05-8575-549e04cfee81",
  • "quote": {
    },
  • "reason_id": "io.habit.policies.other",
  • "created": "2020-08-27T00:00:00.000+0000",
  • "updated": "2020-08-27T00:00:00.000+0000",
  • "active_ts": "2020-08-27T00:00:00.000+0000",
  • "inactive_ts": "2020-08-27T00:00:00.000+0000",
  • "suspended_ts": "2020-08-27T00:00:00.000+0000",
  • "canceled_ts": "2020-08-27T00:00:00.000+0000",
  • "renewed_ts": "2020-08-27T00:00:00.000+0000",
  • "files": [],
  • "coverages": [
    ]
}

All Policies

After a contract is approved by the insurance company, it becomes a Policy.

Use the following method to retrieve an array of created Policies

Response fields

FIELD TYPE DESCRIPTION
elements array Array of policies
size number Number of policies in elements array

Every element in the array must contain the following fields:

Response fields

FIELD TYPE DESCRIPTION
id uuid Policy unique identifier
code string Internal code to identify the Policy
state string Actual policy state (active, inactive, suspend, canceled, renewed)
custom_state string Custom state for the contract (active, inactive, suspended, canceled, renewed)
user_id string ID of the user linked to the policy
quote_id uuid Quote unique identifier
quote object Object with quote's details
reason_id string Reason to explain policy state or custom_state
classes array Array of classes linked to the Policy
created string (date) Policy instance creation date
updated string (date) Policy instance last update date
active_ts string (date) Policy last activation date
inactive_ts string (date) Policy last inactivation date
suspended_ts string (date) Policy last suspension date
canceled_ts string (date) Policy cacelation date
renewed_ts string (date) Policy renovation date
assets array Array of assets linked to the Policy
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

code
string

complete entity code to filter by.

state
string

complete entity state to filter by.

user_id
string <uuid>

user id to filter by.

quote_id
string <uuid>

quote id to filter by.

reason_id
string

reason id to filter by

custom_state
string

custom state to filter by

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Submit policy cancellation

To request a cancellation of a policy to the Insurer

Requirements:

  • Policy state must be different than canceled.
  • Policies with a canceled_ts already defined cannot be re-submitted.

Request fields

FIELD TYPE DESCRIPTION
reason string For available reasons see the chart bellow
when string Available options: on-next-renewal, on-next-payment, immediate, specific_date
canceled_ts string (date) Required if when is immediate or specific_date. Indicates the cancelation date of the policy.

Response fields

FIELD TYPE DESCRIPTION
id uuid Policy unique identifier
code string Internal code to identify the Policy
canceled_ts string (date) Policy cancellation timestamp
reason date policy cancellation reason

Available Reasons

REASON DESCRIPTION
io.habit.policies.distributor.cancellation.other_insurer Choose another insurance company
io.habit.policies.distributor.cancellation.dissatisfaction Dissatisfaction with insurance product
io.habit.policies.distributor.cancellation.bad_sale Bad sale
io.habit.policies.distributor.cancellation.invoice_claim Invoice claim
io.habit.policies.distributor.cancellation.unsolicited Unsolicited insurance
io.habit.policies.distributor.cancellation.inability_support_payment Inability to support payment
io.habit.policies.distributor.cancellation.price_increase Price increase
io.habit.policies.distributor.cancellation.extincted_protected_asset Extinction of the protected asset
io.habit.policies.cancellation.other Other reason
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
reason
required
string

Policy cancellation reason

when
required
string

When must the policy be canceled

Responses

Request samples

Content type
application/json
{
  • "reason": "io.habit.reasons.policies.example",
  • "when": "on-next-renewal"
}

Response samples

Content type
application/json
{
  • "id": "05255a62-8c1e-460f-8b2b-3decbbb40e77",
  • "code": "XYZ-123",
  • "canceled_ts": "2021-05-28T10:10:10.000+0000",
  • "reason": "io.habit.reasons.policies.example"
}

Submit policy termination

To request a termination of a policy to the Insurer

Requirements:

  • Policy state must be different than terminated.
  • Policies with a terminated_ts already defined cannot be re-submitted.

Request fields

FIELD TYPE DESCRIPTION
reason string For available reasons see the chart bellow
when string Available options: on-next-renewal, on-next-payment, immediate, specific_date
terminated_ts string (date) Required if when is immediate or specific_date. Indicates the termination date of the policy.

Response fields

FIELD TYPE DESCRIPTION
id uuid Policy unique identifier
code string Internal code to identify the Policy
terminated_ts string (date) Policy termination timestamp
reason date policy termination reason
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
reason
required
string

Policy termination reason

when
required
string

When must the policy be canceled

terminated_ts
string <timestamp>

Date when the policy was, or will be, terminated

Responses

Request samples

Content type
application/json
{
  • "reason": "io.habit.reasons.policies.example",
  • "when": "specific_date",
  • "terminated_ts": "2025-10-03T10:10:10.000+0000"
}

Response samples

Content type
application/json
{
  • "id": "05255a62-8c1e-460f-8b2b-3decbbb40e77",
  • "code": "XYZ-123",
  • "terminated_ts": "2025-10-03T10:10:10.000+0000",
  • "reason": "io.habit.reasons.policies.example"
}

Submit policy suspension

To request a suspension of a policy to the Insurer

Requirements:

  • Policy state must be different than suspended.
  • Policies with a suspended_ts already defined cannot be re-submitted.

Request fields

FIELD TYPE DESCRIPTION
reason string For available reasons see the chart bellow
when string Available options: on-next-renewal, on-next-payment, immediate, specific_date
suspended_ts string (date) Required if when is immediate or specific_date. Indicates the suspension date of the policy.

Response fields

FIELD TYPE DESCRIPTION
id uuid Policy unique identifier
code string Internal code to identify the Policy
suspended_ts string (date) Policy suspension timestamp
reason date policy suspension reason
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
reason
required
string

Policy suspension reason

when
required
string

When must the policy be canceled

suspended_ts
string <timestamp>

Date when the policy was, or will be, suspended

Responses

Request samples

Content type
application/json
{
  • "reason": "io.habit.reasons.policies.example",
  • "when": "specific_date",
  • "suspended_ts": "2025-10-03T10:10:10.000+0000"
}

Response samples

Content type
application/json
{
  • "id": "05255a62-8c1e-460f-8b2b-3decbbb40e77",
  • "code": "XYZ-123",
  • "suspended_ts": "2025-10-03T10:10:10.000+0000",
  • "reason": "io.habit.reasons.policies.example"
}

Create a Protected Asset and link to a Policy

Create a new Protected Asset and link with an existent and active Policy

Requirements:

  • Policy state must be equal to active

Request fields

FIELD TYPE DESCRIPTION
protectedasset_properties array Array with all protected asset properties to be created

Response fields

FIELD TYPE DESCRIPTION
created object Object with created Protected Asset
customized object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
Array of objects (protectedAssetSpecPropNamespace)

Responses

Request samples

Content type
{
  • "protectedasset_properties": [
    ]
}

Response samples

Content type
application/json
{
  • "href": "/v3/data-layer/quote-protected-assets/f3ec5688-709f-4c94-94dc-88897c9a2e20",
  • "id": "f3ec5688-709f-4c94-94dc-88897c9a2e20",
  • "customized": {
    }
}

Delete Protected Assets linked to a policy

Delete Protected Assets linked to a policy

Requirements:

  • Policy state must be active

Request fields

FIELD TYPE DESCRIPTION
protectedassets array Array with all protected asset ids to be deleted

Request protected assets

FIELD TYPE DESCRIPTION
protectedasset_id uuid Protected Asset ID unique identifier to be deleted.

Response fields

FIELD TYPE DESCRIPTION
n_deleted number Number of protected assets deleted
simulated object Object with all quote properties updated by Insurer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
Array of objects (PADelete)

Responses

Request samples

Content type
application/json
{
  • "protectedassets": [
    ]
}

Response samples

Content type
application/json
{
  • "n_deleted": 1,
  • "simulated": {
    }
}

All Policy's Protected Assets

Use the following method to retrieve an array of Protected Assets linked to a policy

Response fields

FIELD TYPE DESCRIPTION
elements array Array of Protected Assets
size number Number of Protected Assets in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Protected Asset unique identifier
namespace string Namespace of the Protected Asset
quote_id uuid Quote unique identifier
quote object Object with quote's details
classes array Array of classes linked to the Protected Asset
parent_id uuid Parent Protected Asset unique identifier
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

All Policy's Claims

Use the following method to retrieve an array of Claims linked to a policy

Response fields

FIELD TYPE DESCRIPTION
elements array Array of Claims
size number Number of Claims in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Claim unique identifier
code string Internal code to identify the Claim
policy_id uuid ID of the Policy created from this Claim
state string Actual claim state (draft, open, submitted, processing, pending, approved, rejected, canceled)
created string (date) Claim instance creation date
updated string (date) Claim instance last update date
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Attach files to a policy

Attach files to a policy. A file can be a document or picture. Use classes to properly identify file type.

Request fields

FIELD TYPE DESCRIPTION
files array Array with all files to be attached

Each asset must contain the following information

Request assets

FIELD TYPE DESCRIPTION
name string Filename from file-upload result
uri url File url from file-upload result
classes array Array of classes to be attached to the file. Find bellow available classes

Response fields

FIELD TYPE DESCRIPTION
files array Array with all attached files

Avaliable Policy Asset Classes

CLASSES
io.habit.trackableassets.type.document
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
Array of objects (attachFiles)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Update policy coverages

Update policy coverages

Requirements:

  • To update Policy's coverages and properties

Request fields

FIELD TYPE DESCRIPTION
coverages array Array with all coverages to be created/changed

Each coverage must contain the following information

Request Coverages

FIELD TYPE DESCRIPTION
coverage_id uuid Quote Coverage ID unique identifier to be created or updated. Either this or namespace must be specified.
namespace string Quote Coverage Spec namespace to be created or updated. Either this or coverage_id must be specified.
properties array (optional) Data to be set in property

Each property must contain the following information

Request Properties

FIELD TYPE DESCRIPTION
quotecoveragepropertyspec_id uuid Quote Coverage Property Spec unique identifier to be created or updated. Either this or namespace must be specified.
namespace string Quote Coverage Property Spec namespace to be created or updated. Either this or quotecoveragepropertyspec_id must be specified.
data string (required) Data to be set in property

Response fields

FIELD TYPE DESCRIPTION
coverages array Array with all coverages
n_updated number Number of quote coverage properties updated
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
Array of objects (coverage)

Responses

Request samples

Content type
{
  • "coverages": [
    ]
}

Response samples

Content type
application/json
{
  • "coverages": [
    ],
  • "n_updated": 1
}

Contributions

All Contributions

Use the following method to retrieve an array of contributions from an insurance product

Response fields

FIELD TYPE DESCRIPTION
elements array Array of contributions
size number Number of contributions in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Contribution unique identifier
amount float Contribution amount
quote_id uuid Quote unique identifier
state string Contribution state (see below for details)
tags array Tags used to identify contribution type (see below for details)
currency_id string Currency code (ISO 4217)
country_id string Country code (ISO 3166)
user_id uuid Contribution User ID. Same as Policy User
emission_date string (Date) Payments' emission date when the Contribution takes effect. In some cases could have the same value as created
expiration_date string (Date) Payments' expiration date. After that, the Contribution is no longer acceptable. In some cases could have the same value as created
due_date string (Date) Payments' due date. after that the payment is considered overdue. In some cases could have the same value as created
initial_provision_date string (Date) Payments' start date representing the period for which the payment applies
final_provision_date string (Date) Payments' end date representing the period for which the payment applies
reason_id string Reason to explain contribution state
authorized_ts string (Date) Date when the payment state change to authorized
canceled_ts string (Date) Date when the payment state change to canceled
error_ts string (Date) Date when the payment state change to error
paid_ts string (Date) Date when the payment state change to paid
refunded_ts string (Date) Date when the payment state change to refunded
created string (date) Date when Contribution was created
updated string (date) Date when Contribution was updated

Contribution States

DISPLAY NAME STATE DESCRIPTION
Pending pending Contribution pending
Paid paid Contribution paid successfully
Error error Contribution failed
Canceled canceled Contribution got canceled within a period of time, before reaching a paid state
Refunded refunded Contribution was refunded

Contribution Tags

DISPLAY NAME DESCRIPTION
new_subscription Contribution realted to a new contract subscription
recurrence Contribution related to a recurrence paymente for a contract
upfront_premium Contribution related to a premium paid in advance
Authorizations:
OAuth2 Authorization
query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

quote_id
string <uuid>

quote id to filter by.

id
string <uuid>

entity id to filter by.

state
string

complete entity state to filter by.

currency_id
string

currency id to filter by

country_id
string

country id to filter by

reason_id
string

reason id to filter by

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

All Policy Contributions

Use the following method to retrieve an array of Contributions linked to policy

Response fields

FIELD TYPE DESCRIPTION
elements array Array of Contributions
size number Number of Contributions in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Contribution unique identifier
amount float Contribution amount
quote_id uuid Quote unique identifier
state string Contribution state (see below for details)
tags array Tags used to identify contribution type (see below for details)
currency_id string Currency code (ISO 4217)
country_id string Country code (ISO 3166)
user_id uuid Contribution User ID. Same as Policy User
emission_date string (Date) Payments' emission date when the Contribution takes effect. In some cases could have the same value as created
expiration_date string (Date) Payments' expiration date. After that, the Contribution is no longer acceptable. In some cases could have the same value as created
due_date string (Date) Payments' due date. after that the payment is considered overdue. In some cases could have the same value as created
initial_provision_date string (Date) Payments' start date representing the period for which the payment applies
final_provision_date string (Date) Payments' end date representing the period for which the payment applies
reason_id string Reason to explain contribution state
authorized_ts string (Date) Date when the payment state change to authorized
canceled_ts string (Date) Date when the payment state change to canceled
error_ts string (Date) Date when the payment state change to error
paid_ts string (Date) Date when the payment state change to paid
refunded_ts string (Date) Date when the payment state change to refunded
created string (date) Date when Contribution was created
updated string (date) Date when Contribution was updated

Contribution States

DISPLAY NAME STATE DESCRIPTION
Pending pending Contribution pending
Paid paid Contribution paid successfully
Error error Contribution failed
Canceled canceled Contribution got canceled within a period of time, before reaching a paid state
Refunded refunded Contribution was refunded

Contribution Tags

DISPLAY NAME DESCRIPTION
new_subscription Contribution realted to a new contract subscription
recurrence Contribution related to a recurrence paymente for a contract
upfront_premium Contribution related to a premium paid in advance
Authorizations:
OAuth2 Authorization
query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

state
string

complete entity state to filter by.

currency_id
string

currency id to filter by

country_id
string

country id to filter by

reason_id
string

reason id to filter by

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Add a new Transaction to a Contribution

Use the following method add a new Transaction to a Contribution.

Request fields

FIELD TYPE DESCRIPTION
state string Transaction state (see below for details)
cdata object (optional) Transaction Context data

Transaction States

DISPLAY NAME STATE DESCRIPTION
Pending pending Transaction pending. Indicates Distributor has sent an invoice to the customer
Paid received Indicates the contribution has been received by Distributor
Paid sent_for_settle Transaction sent_for_settle. When Distributor confirms the contribution has been sent to Habit
Refunded refunded To indicate a Contribution has been refunded
Error error Contribution failed
Canceled canceled Contribution got canceled within a period of time, before reaching a paid state

Response fields

FIELD TYPE DESCRIPTION
id uuid Transaction unique identifier
payment_id uuid Contribution unique identifier
state string Transaction state (see below for details)
final_state boolean Transaction with a final state
cdata object Transaction Context data
created string (date) Date when quote was created
updated string (date) Date when quote was updated
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

id
required
string
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired contribution.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
state
string
cdata
object

Responses

Request samples

Content type
application/json
{
  • "state": "received",
  • "cdata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "02ac6178-267a-4c0e-af2f-58f2cf76316a",
  • "payment_id": "98d0be93-fa33-4e67-acd4-d6835b8f8579",
  • "state": "sent_for_settle",
  • "final_state": false,
  • "cdata": { },
  • "created": "2020-09-18T14:15:56.095+0000",
  • "updated": "2020-09-18T14:15:56.095+0000"
}

Attach files to a contribution

Attach files to a contribution. A file can be a document or picture. Use classes to properly identify file type.

Request fields

FIELD TYPE DESCRIPTION
files array Array with all files to be attached

Each asset must contain the following information

Request assets

FIELD TYPE DESCRIPTION
name string Filename from file-upload result
uri url File url from file-upload result
classes array Array of classes to be attached to the file. Find bellow available classes

Response fields

FIELD TYPE DESCRIPTION
files array Array with all attached files

Avaliable Contribution Asset Classes

For "Invoice" use the following 3 classes

CLASSES
io.habit.payment.asset
io.habit.payment.asset.invoice
io.habit.trackableassets.type.document

For "Premium Notice" use the following 3 classes

CLASSES
io.habit.payment.asset
io.habit.payment.asset.notice
io.habit.trackableassets.type.document
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

quote_id
required
string <uuid>
Example: 1ea47dd4-6c9c-4b05-8575-549e04cfee81

The ID of the desired quote.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
Array of objects (attachFiles)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

All Contribution Transactions

Use the following method to retrieve an array of Transactions linked to Contribution

Response fields

FIELD TYPE DESCRIPTION
elements array Array of Transactions
size number Number of Transactions in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Transaction unique identifier
payment_id uuid Contribution unique identifier
state string Transaction state (see below for details)
final_state boolean Transaction with a final state
cdata object Transaction Context data

Transaction States

DISPLAY NAME STATE DESCRIPTION
Pending pending Transaction pending. Indicates Distributor has sent an invoice to the customer
Paid received Indicates the contribution has been received by Distributor
Paid sent_for_settle Transaction sent_for_settle. When Distributor confirms the contribution has been sent to Habit
Paid settled Habit confirms contribution received. (final state)
Refunded refunded To indicate a Contribution has been refunded
Error error Contribution failed
Canceled canceled Contribution got canceled within a period of time, before reaching a paid state
Authorizations:
OAuth2 Authorization
query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

state
string

complete entity state to filter by.

final_state
boolean

final_state value to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Claims

Retrieve claim property specs

Retrieve all available claim specs to update claim properties

Response fields

FIELD TYPE DESCRIPTION
elements array Array with all available claim properties
size number Number of properties in elements
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

version_id
required
string <uuid>
Example: 58970c9d-7c6c-4b4e-9664-ec3001899ca0

The ID of the desired version.

query Parameters
id
string <uuid>

entity id to filter by.

namespace
string

complete entity namespace to filter by.

label
string

complete entity label to filter by.

force_data
boolean

boolean indicating force_data state to filter by.

schema
string

complete entity schema to filter by.

order_index
number <integer>

entity order_index to filter by.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Submit a claim for a policy by ID

Use the following method to submit a new claim to a policy

Requirements:

  • Policy state must be equal to active

Request fields

FIELD TYPE DESCRIPTION
claim_properties array Array with all claim properties to be created (properties id or namespace can be used)

Response fields

FIELD TYPE DESCRIPTION
id uuid Claim unique identifier
code string Internal code to identify the Claim
state string Actual claim state (draft, open, submitted, processing, pending, approved, rejected)
created object Object with created Offer
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

policy_id
required
string <uuid>
Example: bb6e1769-5685-4fc8-b9f5-f29a9ac6771e

The ID of the desired policy.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
Array of objects (claimSpecPropNamespace)

Responses

Request samples

Content type
{
  • "claim_properties": [
    ]
}

Response samples

Content type
application/json
{
  • "created": {
    }
}

Single Claim

Use the following method to retrieve information about a Claim

Response fields

FIELD TYPE DESCRIPTION
id uuid Claim unique identifier
code string Internal code to identify the Claim
policy_id uuid ID of the Policy associated to this Claim
state string Actual claim state (draft, open, submitted, processing, pending, approved, rejected)
created string (date) Claim instance creation date
updated string (date) Claim instance last update date
properties array Array with all protected asset properties
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

claim_id
required
string <uuid>
Example: f3ec5688-709f-4c94-94dc-88897c9a2e20

The ID of the desired claim.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "id": "bb6e1769-5685-4fc8-b9f5-f29a9ac6771e",
  • "code": "ABC-789",
  • "policy_id": "1ea47dd4-6c9c-4b05-8575-549e04cfee81",
  • "state": "pending",
  • "created": "2020-08-27T00:00:00.000+0000",
  • "updated": "2020-08-27T00:00:00.000+0000"
}

All Claims

Use the following method to retrieve an array of claims.

Response fields

FIELD TYPE DESCRIPTION
elements array Array of claims
size number Number of claims in elements array

Every element in the array must contain the following fields:

Response fields

FIELD TYPE DESCRIPTION
id uuid Claim unique identifier
code string Internal code to identify the Claim
policy_id uuid ID of the Policy associated to this Claim
state string Actual claim state (draft, open, submitted, processing, pending, approved, rejected)
created string (date) Claim instance creation date
updated string (date) Claim instance last update date
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

code
string

complete entity code to filter by.

state
string

complete entity state to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Update Claim's properties

Update Claim's properties according to payload

Request fields

FIELD TYPE DESCRIPTION
properties array Array with all claim properties to be updated

Each property must contain the following information

Request Properties

FIELD TYPE DESCRIPTION
claimspec_id uuid Claim Property Spec unique identifier to be created or updated. Either this or namespace must be specified.
namespace string Claim Property Spec namespace to be created or updated. Either this or claimpropertyspec_id must be specified.
data string (required) Data to be set in property

Response fields

FIELD TYPE DESCRIPTION
properties array Array with all created or updated properties
n_updated number Number of quote properties updated
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

claim_id
required
string <uuid>
Example: f3ec5688-709f-4c94-94dc-88897c9a2e20

The ID of the desired claim.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema:
required
Array of objects (Claim Property Create Namespace)

Responses

Request samples

Content type
{
  • "properties": [
    ]
}

Response samples

Content type
application/json
{
  • "properties": [
    ],
  • "n_updated": 1
}

Submit claim cancellation

To request a cancellation of a claim to the Insurer

Requirements:

  • Claim state must be different than approved, rejected or canceled.

    Request fields

FIELD TYPE DESCRIPTION
reason string For available reasons see the chart bellow

Response fields

FIELD TYPE DESCRIPTION
id uuid Claim unique identifier
canceled_ts string (date) Claim cancellation timestamp
reason date claim cancellation reason
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

claim_id
required
string <uuid>
Example: f3ec5688-709f-4c94-94dc-88897c9a2e20

The ID of the desired claim.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
reason
required
string

Claim cancellation reason

Responses

Request samples

Content type
application/json
{
  • "reason": "io.habit.reasons.claims.example"
}

Response samples

Content type
application/json
{
  • "id": "05255a62-8c1e-460f-8b2b-3decbbb40e77",
  • "code": "XYZ-123",
  • "canceled_ts": "2021-05-28T10:10:10.000+0000",
  • "reason": "io.habit.reasons.claims.example"
}

Attach files to a claim

Attach files to a claim. A file can be a document, picture, video, audio or json. Use classes to properly identify file type.

Request fields

FIELD TYPE DESCRIPTION
files array Array with all files to be attached

Each asset must contain the following information

Request assets

FIELD TYPE DESCRIPTION
name string Filename from file-upload result
uri url File url from file-upload result
icon url (optional) File icon from file-upload result
image url (optional) File image from file-upload result
classes array (optional) Array of classes to be attached to the file. Find bellow available classes

Response fields

FIELD TYPE DESCRIPTION
files array Array with all attached files

Avaliable Asset Classes

TYPE DESCRIPTION
io.habit.trackableassets.type.document Documents (*.pdf)
io.habit.trackableassets.type.photo Images (*.png, *.jpg)
io.habit.trackableassets.type.video Videos (*.mp4)
io.habit.trackableassets.type.json Json
io.habit.trackableassets.type.audio Audio
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

claim_id
required
string <uuid>
Example: f3ec5688-709f-4c94-94dc-88897c9a2e20

The ID of the desired claim.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
Array of objects (attachFiles)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Payables

All Payables

Use the following method to retrieve an array of payables from an insurance product

Response fields

FIELD TYPE DESCRIPTION
elements array Array of payables
size number Number of payables in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Payable unique identifier
amount float Payable amount
claim_id uuid Claim unique identifier
state string Payable state (see below for details)
currency_id string Currency code (ISO 4217)
country_id string Country code (ISO 3166)
user_id uuid Payable User ID. Same as Policy User
start_date string (Date) Payable date
end_date string (Date) Payable date
created string (date) Date when Payable was created
updated string (date) Date when Payable was updated

Payable States

DISPLAY NAME STATE DESCRIPTION
Pending pending Payable pending
Paid paid Payable paid successfully
Error error Payable failed
Canceled canceled Payable got canceled within a period of time, before reaching a paid state
Refunded refunded Payable was refunded
Authorizations:
OAuth2 Authorization
query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

claim_id
string <uuid>

claim id to filter by.

id
string <uuid>

entity id to filter by.

state
string

complete entity state to filter by.

currency_id
string

currency id to filter by

country_id
string

country id to filter by

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

All Claim Payables

Use the following method to retrieve an array of Payables linked to claim

Response fields

FIELD TYPE DESCRIPTION
elements array Array of Payables
size number Number of Payables in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Payable unique identifier
amount float Payable amount
claim_id uuid Claim unique identifier
state string Payable state (see below for details)
currency_id string Currency code (ISO 4217)
country_id string Country code (ISO 3166)
user_id uuid Payable User ID. Same as Policy User
start_date string (Date) Period start date when the Payable takes effect. In some cases could have the same value as created
end_date string (Date) Period end date when the Payable takes effect. In some cases could have the same value as created
created string (date) Date when Payable was created
updated string (date) Date when Payable was updated

Payable States

DISPLAY NAME STATE DESCRIPTION
Pending pending Payable pending
Paid paid Payable paid successfully
Error error Payable failed
Canceled canceled Payable got canceled within a period of time, before reaching a paid state
Refunded refunded Payable was refunded
Authorizations:
OAuth2 Authorization
query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

state
string

complete entity state to filter by.

currency_id
string

currency id to filter by

country_id
string

country id to filter by

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Add a new Transaction to a Payable

Use the following method add a new Transaction to a Payable.

Request fields

FIELD TYPE DESCRIPTION
state string Transaction state (see below for details)

Transaction States

DISPLAY NAME STATE DESCRIPTION
Pending pending Transaction pending. Indicates Habit has received instructions to do a payable to the customer
Paid sent Indicates the paybale has been transfered to the customer
Paid sent_for_settle Transaction sent_for_settle. When Distributor/Insurer confirms the payable has been sent to Habit
Paid settled Habit confirms payable received. (final state)
Refunded refunded To indicate a Payable has been refunded
Error error Payable failed
Canceled canceled Payable got canceled within a period of time, before reaching a paid state

Response fields

FIELD TYPE DESCRIPTION
id uuid Transaction unique identifier
payment_id uuid Payable unique identifier
state string Transaction state (see below for details)
final_state boolean Transaction with a final state
cdata object Transaction Context data
created string (date) Date when quote was created
updated string (date) Date when quote was updated
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired payable.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
state
string

Responses

Request samples

Content type
application/json
{
  • "state": "pending"
}

Response samples

Content type
application/json
{
  • "id": "02ac6178-267a-4c0e-af2f-58f2cf76316a",
  • "payment_id": "98d0be93-fa33-4e67-acd4-d6835b8f8579",
  • "state": "sent_for_settle",
  • "final_state": false,
  • "cdata": { },
  • "created": "2020-09-18T14:15:56.095+0000",
  • "updated": "2020-09-18T14:15:56.095+0000"
}

Attach files to a payable

Attach files to a payable. A file can be a document or picture. Use classes to properly identify file type.

Request fields

FIELD TYPE DESCRIPTION
files array Array with all files to be attached

Each asset must contain the following information

Request assets

FIELD TYPE DESCRIPTION
name string Filename from file-upload result
uri url File url from file-upload result
classes array Array of classes to be attached to the file. Find bellow available classes

Response fields

FIELD TYPE DESCRIPTION
files array Array with all attached files

Avaliable Payable Asset Classes

CLASSES
io.habit.payment.asset
io.habit.payment.asset.invoice
io.habit.trackableassets.type.document
Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired payable.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
Array of objects (attachFiles)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

All Payable Transactions

Use the following method to retrieve an array of Transactions linked to Payable

Response fields

FIELD TYPE DESCRIPTION
elements array Array of Transactions
size number Number of Transactions in elements array

Every element in the array must contain the following fields:

FIELD TYPE DESCRIPTION
id uuid Transaction unique identifier
payment_id uuid Payable unique identifier
state string Transaction state (see below for details)
final_state boolean Transaction with a final state
cdata object Transaction Context data

Transaction States

DISPLAY NAME STATE DESCRIPTION
Pending pending Transaction pending. Indicates Habit has received instructions to do a payable to the customer
Paid sent Indicates the paybale has been transfered to the customer
Paid sent_for_settle Transaction sent_for_settle. When Distributor/Insurer confirms the payable has been sent to Habit
Paid settled Habit confirms payable received. (final state)
Refunded refunded To indicate a Payable has been refunded
Error error Payable failed
Canceled canceled Payable got canceled within a period of time, before reaching a paid state
Authorizations:
OAuth2 Authorization
query Parameters
page_size
number <integer>
Default: 20

A limit on the number of objects to be returned. Default is 20, minimum is 1, maximum is 100.

page_start_index
number <integer>
Default: 0

Offset the list of returned results by this amount. Default is 0.

order_by
string
Example: order_by=-created

The results can be in ascendent (+) or descendent (-) order. Use + or - before the field name to use a specific order.

fields
string
Example: fields=id,name

comma separeted fields to return in payload.

id
string <uuid>

entity id to filter by.

state
string

complete entity state to filter by.

final_state
boolean

final_state value to filter by.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "size": 1
}

Files

File Upload

Uploads a new file

Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

header Parameters
Authorization
required
string
Example: Bearer {access_token}
Content-Type
required
string
Default: multipart/form-data
Request Body schema:
content
required
string <binary>

file to upload

Responses

Custom Actions

Custom Actions

Custom actions defined by project and distributor

Authorizations:
OAuth2 Authorization
path Parameters
id
required
string <uuid>
Example: 0cc9de4b-1b70-406d-b67b-766cf9c53cca

The ID of the desired insurance-product.

action
required
string
Example: help

custom action to be executed.

header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
data
object

Object with key value pairs to be used in action context

Responses

Request samples

Content type
application/json
{
  • "data": { }
}

Response samples

Content type
application/json
{
  • "custom_data": { }
}

Third Party User Sync

Third Party User Sync

Proceed with the retrieval, updating, or creation of the user on our platform

Request fields

FIELD TYPE DESCRIPTION
target string selfcare, sales_portal_authenticated_user or customer_selfcare
remote_code string (optional) Distributor custom code to be linked to the user
name string required if target is selfcare
email string User's e-mail, required if target is selfcare
mobile string (optional) User's mobile number
type string (optional) seller or lead
user_id uuid required if target is customer_selfcare or sales_portal_authenticated_user
insuranceproduct_id uuid required if target is customer_selfcare or sales_portal_authenticated_user
policy_id uuid required if target is customer_selfcare
distributionpoint_id string (optional)
distributionpoint string (optional)
scope array required if target is selfcare
redirect_uri string (optional)
redirect_context string (optional)

Response fields

FIELD TYPE DESCRIPTION
message string user friendly result description
success boolean true or false
user dict dictionary with user details
webview_uri string webview url to redirect after successfully retrieving the authentication details
Authorizations:
OAuth2 Authorization
header Parameters
Content-Type
required
string
Default: application/json
Authorization
required
string
Example: Bearer {access_token}
Request Body schema: application/json
One of
target
string
insuranceproduct_id
uuid
user_id
uuid
policy_id
uuid
object

Responses

Request samples

Content type
application/json
Example
{
  • "target": "customer_selfcare",
  • "insuranceproduct_id": "e1c2c4fa-2d95-4d1b-9b17-8e3030e073ff",
  • "user_id": "7817293f-6c01-4a04-b8fb-894294dc5d8f",
  • "policy_id": "bec698c9-c421-46c3-8320-6d60d1d9a989",
  • "redirect_context": {
    }
}

Response samples

Content type
application/json
Example
{
  • "message": "user retrieved",
  • "success": true,
  • "user": {
    },
  • "webview_uri": "https://my.habit.io/partners/:uuid/products/:uuid/third-party-auth?client_id=d5ceaae9-0c2c-602e-83c1- 42a32c53982b&confirmation_hash=f0..rl&redirect_uri=/%3Fcontext%3DewogICAgImhhYml0X2lkIjogIjY1NDkwNzc4LTQ2NGYtNDg4NS05N2U2LTM0M zEzZjE2ZmQyMiIsCiAgICAibGFuZ3VhZ2UiOiAiUFQiLAoJInN1YnNjcmliZXJzIjogWwoJCXsKCQkJImhhYml0X2lkIjogImM0OWI4NWQ4LTE1NmEtNDQ2MS1iNWM wLTM4MGI3NWE1M2Q0ZiIKCQl9CgldLAoJImFzc29jaWF0ZXMiOiBbCgkJewoJCQkiaGFiaXRfaWQiOiAiYzQ5Yjg1ZDgtMTU2YS00NDYxLWI1YzAtMzgwYjc1YTUzZ DRmIgoJCX0KCV0KfQ%3D%3D"
}

Error Handling

In this seccion you will find possible error codes accross the api

Response errors will have the following format

{ "error": "error message", "code": 0 }

Error codes

CODE MESSAGE
4021 Session belongs to a different user
4022 Invalid fingerprint session
4090 Invalid mobile number, required E.164 international format
4091 Invalid value for email
4092 Invalid value for partner_code
4093 Missing user information
4140 User already exists
1200 Missing required data
1201 Key must not be empty
1202 Invalid value type
1203 Invalid value for data
1210 Invalid field name
1810 page_size out of range [:dynamic_content]
9000 Quote generic error
9001 Retrieve Quote failed
9002 Quote from another service
9003 You dont have access to this quote
9004 Quote expired
9005 Error: user-create call
9006 Invalid product
9007 You cant change an immutable property: [:dynamic_content]
9008 Missing required data for property: [:dynamic_content]
9009 The code [:dynamic_content] already belongs to another quote
9010 There are more than one existent policy holder with the same identifier to be selected
9011 Properties not found on payload
9012 Duplicated property namespaces found on payload
9030 Quote property not found with classes
9031 Invalid data for Quote property with namespace [:dynamic_content]
9032 Quote properties cant be changed with quote in current state [:dynamic_content]
9033 Invalid data value for insurer [:dynamic_content]
9034 Error on insurer api [:dynamic content]
9035 Quote properties with duplicated namespace found
9200 Protected Asset generic error
9201 Retrieve Protected Asset failed
9202 Protected Asset from another service
9203 Invalid protectedassets specs
9230 PA property not found with classes
9231 Invalid data for PA property with namespace [:dynamic_content]
9232 Invalid data in specific insurer validation process for PA property with namespace [:dynamic content]
9233 PA properties with duplicated namespace found
9300 Coverage generic error
9301 There is no Coverages to be deleted in this Quote
9302 Quote Coverages cant be changed with quote in current state [:dynamic_content]
9303 None of the sent Coverages are valid to be deleted
9304 Unknown coverage [:dynamic_content]
9305 Invalid EnabledServiceCoverages [:dynamic_content]
9306 Quote Coverages Properties with duplicated namespace found
9400 Policy generic error
9401 Retrieve Policy failed
9402 Policy from another service
9403 You dont have access to this policy
9404 Invalid policy pin
9405 You cant change policy state to [:dynamic_content]
9406 Invalid policy state [:dynamic_content]
9407 The code [:dynamic_content] already belongs to another policy
9408 Policy is not active
9409 Policy in renewed state. Cant be updated.
9410 Policy already in state [:dynamic_content]
9411 Invalid when parameter [:dynamic_content]
9412 Policy already set to be canceled on [:dynamic_content]
9413 Invalid cancellation reason [:dynamic_content]
9414 It was not possible to validate cancellation [:dynamic_content]
9500 Insuree generic error
9501 Retrieve Insuree failed
9502 Insuree from another service
9503 Invalid Policy Holder
9504 Policy Holder cant be updated in state [:dynamic_content]
9531 Invalid data for Policy Holder property with namespace [:dynamic_content]
9532 Policy Holder properties with duplicated namespace found
9600 Claim generic error
9700 Block generic error
9800 Subscription generic error
9801 Insurer API error
9900 Distributor generic error
9901 Quote cant be submitted in state: [:dynamic_content]
9902 Missing user information
9903 Invalid user information
9908 Invalid user namespace
9910 You dont have access to this user
9911 User from another app
9920 You dont have access to this product
9970 BRE generic error
9971 Invalid action: [:dynamic_content]
9980 Payment generic error
9981 Invalid confirmation hash for transaction
9982 Contribution is already on a final state
9983 Latest transaction is already on [:dynamic_content] state
9984 Missing Payment configuration
9985 Invalid Payment
9986 Invalid transaction state

Pagination

All list API resources have support to fetch paginated results. This resources share a common structure, taking at least these two parameters page_start_index and page_size. Combined the full collection can be retrieved.

Default amount of elements by page is 20, maximum is currently 100. Additionally results can be sorted in chronological (or reverse) order.

A status_code 204 means there are no results found with the requested parameters.

Example:

For a full collection of 40 elements.

GET /v3/insurance-products/{id}/policies?page_start_index=0&page_size=20&order_by=created
Response: 200

GET /v3/insurance-products/{id}/policies?page_start_index=20&page_size=20&order_by=created
Response: 200

GET /v3/insurance-products/{id}/policies?page_start_index=40&page_size=20&order_by=created
Response: 204

GET /v3/insurance-products/{id}/policies?page_size=101&order_by=created
Response: 412
{ "code": 1810, "error": "Page size out of range [1 - 100]" }

Webhooks Contracts

Habit notifies distributor of a contract changed properties

Send information about the properties updated

Authorizations:
ApiKeyAuth
Request Body schema: application/json
insuraceproduct_id
string <uuid>
policy_id
string <uuid>
policy_code
string

Policy code

Array of objects (propertiesList)
Array of objects (propertiesList)
Array of objects (updatedProtectedAssets)
Array of objects (updatedCoverages)

Responses

Request samples

Content type
application/json
{
  • "insuraceproduct_id": "a99ed66f-4360-4ebb-9039-0c5494fee9c4",
  • "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",
  • "policy_code": "ABC-123",
  • "quote_properties": [
    ],
  • "policyholder_properties": [
    ],
  • "protectedassets": [
    ],
  • "coverages": [
    ]
}

Habit notifies distributor of a contract cancelation

Send information about the contract cancelation

Authorizations:
ApiKeyAuth
Request Body schema: application/json
insuraceproduct_id
string <uuid>
policy_id
string <uuid>
policy_code
string

Policy code

cancelation_ts
string <timestamp>
reason_id
string

Responses

Request samples

Content type
application/json
{
  • "insuraceproduct_id": "a99ed66f-4360-4ebb-9039-0c5494fee9c4",
  • "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",
  • "policy_code": "ABC-123",
  • "cancelation_ts": "2021-05-28T10:10:10.000+0000",
  • "reason_id": "io.habit.policies.distributor.cancellation.extincted_service"
}