Skip to main content

Remove an entity from your portfolio

Abstract

Learn how to start the entity offboarding process using the API. This removes the entity from your portfolio, along with any associated assessments, tasks, and data overrides.

Use the DELETE /entities/{entity_id} endpoint to remove an entity from your portfolio by starting the entity offboarding process.

Removing an entity deletes it from your portfolio, along with any associated assessments, tasks, and data overrides. If you choose to add the entity back to your portfolio in the future, it is processed as a new entity and may incur additional fees.

Prerequisites 

The entity must not be in a state that prevents offboarding, for example, it is still being onboarded.

Request

To remove an entity from your portfolio, send a DELETE request to the /entities/{entity_id} endpoint.

The path parameter entity_id should contain the ID of the entity to remove.

For example:

curl --request "DELETE" \
 "https://{api_region}/v5/entities/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ 
 --header "apikey: YOUR_API_KEY"

Replace {api_region} with the domain from your region's base URL.

To authenticate your request, include the apikey: YOUR_API_KEY header. See Manage API keys for more information.

Response

This endpoint starts an asynchronous offboarding job and returns a job ID. Use this job ID to check the job status using the /entities/jobs/{job_id} endpoint.

The response code indicates whether an offboarding job has been created, is already running, or can't be started:

  • A 202 Accepted response indicates that the offboarding job has been accepted and created.

    { 
 "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

  • A 200 OK response indicates that an offboarding job for this entity is already in progress or has already been completed.

    { 
 "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Troubleshooting

  • If you receive a 401 Unauthorized response, make sure the apikey header is included and contains a valid key. Check that you are using the correct base URL for your region, and if IP allow listing is enabled, verify your request originates from an allowed IP address.

  • A response of 403 Forbidden means you don't have permission to remove this entity.

  • If you receive a 404 Not Found response, check the entity_id path parameter is correct.

  • A response of 409 Conflict means the entity is in a state that prevents offboarding, for example, it is still being onboarded.

  • If you receive a 500 Internal server error response, it means the server couldn't fulfill your request due to an unexpected error. If you can't resolve the issue internally, email our Client Service team.

For a full list of the possible error codes, view the API reference.

Additional information 

The collection of entities going through your organization's assessment and monitoring processes.

The process of evaluating an entity in your portfolio using a specified workflow. An assessment determines whether the entity meets your defined criteria and may involve multiple steps. An entity can be going through multiple assessments at the same time.

A manual action generated when a workflow step can't be automated and requires human intervention. For example, supplying missing data or resolving screening matches.