Modifying accounts

PATCHing accounts

Use the following endpoint to PATCH values on an existing account:

  • PATCH /account/v1/accounts/{accountId}

For example, the following call changes the preferred coverage and settlement currencies for account pc:477 to Canadian dollars (cad).

PATCH /account/v1/accounts/pc:477

{
  "data": {
    "attributes": {
        "preferredCoverageCurrency": {
            "code": "cad"
        },
        "preferredSettlementCurrency": {
            "code": "cad"
        }
    }
  }
}

Merging accounts

Merging accounts is the action of collapsing two accounts into one. One account is designated as the source account. The other is the target account. During the merge, information is moved from the source to the target, such as the source account's policies, policy transactions, notes, activities, and other data. After the merge, the source account is deleted and only the target account remains. For more information on merging accounts, see the Application Guide.

Use the following endpoint to merge accounts:

  • POST /account/v1/accounts/{accountId}/merge

The POST is executed from the target account (the account that will be retained). The request requires a payload. This is the syntax for the URL and the payload.

POST /account/v1/accounts/{targetAccountId}/merge

{
  "data": {
    "attributes": {
        "account": {
            "id": "<sourceAccountId>"
        }
    }
  }
}

For example, the following call merges source account pc:1010 into target account pc:33.

POST /account/v1/accounts/pc:33/merge

{
  "data": {
    "attributes": {
        "account": {
            "id": "pc:1010"
        }
    }
  }
}

Withdrawing accounts

Some accounts are created for prospects that do not elect to bind any policies and the insurer does not expect the account to bind any policies in the future. In these cases, the insurer can withdraw the account.

To withdraw an account through Cloud API, use the following endpoint. The call does not require a request body:

  • POST /account/v1/accounts/{accountId}/withdraw

For example, the following call withdraws account pc:477.

POST /account/v1/accounts/pc:477/withdraw

<no request body>

Withdrawing an account changes the account status to "Withdrawn".

Note that you can only withdraw accounts whose status is "Pending". (In order to have this status, the account must have no policies.)

Reopening accounts

To reopen a withdrawn account through Cloud API, use the following endpoint. The call does not require a request body:

  • POST /account/v1/accounts/{accountId}/reopen

For example, the following call withdraws account pc:477 (assuming the account has been withdrawn).

POST /account/v1/accounts/pc:477/reopen

<no request body>

Reopening an account changes the account status to "Pending".