> ## Documentation Index > Fetch the complete documentation index at: https://docs.trusto.io/llms.txt > Use this file to discover all available pages before exploring further. # Trusto API Documentation > API endpoints for ERP integration # Authentication & Authorization ## Creating API credentials 1. Go to [https://app.trusto.io](https://app.trusto.io) and open **Settings → API Credentials**. 2. As an Organization Owner, generate an API key for your organization. 3. Save the key when it is created. It cannot be viewed again. 4. Send the key in the `X-API-KEY` header with every API request. API credentials screen The examples below use the production API at `https://api.trusto.io`. *** # Alerts ## Retrieve all alerts Returns a paginated collection of alerts available to the organization associated with the API key. ### Endpoint `GET /api/v1/alerts` ### Request headers | Header | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------- | | X-API-KEY | string | Yes | API key generated in Trusto. | | Content-Type | string | No | Use `application/json`. | ### Query parameters | Parameter | Type | Required | Description | | -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ | | page | integer | No | Zero-based page index. Defaults to `0`. | | size | integer | No | Results per page. Defaults to `10`. | | startDate | string | No | Alert date on or after this date, in `YYYY-MM-DD` format. | | endDate | string | No | Alert date on or before this date, in `YYYY-MM-DD` format. | | transactionStartDate | string | No | Transaction date on or after this date, in `YYYY-MM-DD` format. | | transactionEndDate | string | No | Transaction date on or before this date, in `YYYY-MM-DD` format. | | provider | string | No | One or more comma-separated providers: `ETHOCA`, `VERIFI`, or `CDRN`. | | type | string | No | One or more comma-separated alert types. | | status | string | No | One or more comma-separated statuses: `OPEN`, `RESOLVED`, `REFUNDED`, `CHARGEBACK`, `EXPIRED`, or `INVALID`. | | descriptor | string | No | Merchant descriptor filter. | | outcome | string | No | One or more comma-separated outcome values. | | expired | boolean | No | Filter by whether `expiredAt` is populated. | | expiresIn | integer | No | Return unresolved alerts expiring within this many hours. | | sortField | string | No | Alert field used for sorting. | | sortOrder | string | No | `ASC` or `DESC`. | | q | string | No | Search provider ID, merchant descriptor, card BIN, or last four digits. | ### Sample request ```bash theme={null} curl "https://api.trusto.io/api/v1/alerts?page=0&size=10&startDate=2024-10-01&endDate=2024-11-30&provider=ETHOCA" \ -H "X-API-KEY: YOUR_API_KEY" ``` ### Response ```json theme={null} { "data": [ { "id": "c8edf8a4-4e4d-4821-af34-9ed2995cbd8b", "providerId": "6d9e6dc7-3cf7-4a9d-ae66-97bcf86b80d2", "provider": "ETHOCA", "type": "ETHOCA_CONFIRMED_FRAUD", "alertTimeStamp": "2024-11-10T19:07:56.293Z", "enrollmentId": "554df940-b344-40ab-85fd-fc7b89c86ad1", "companyId": "7224a209-dc9c-4101-846d-2bc57eacd2b7", "issuer": "BARCLAYS", "cardBin": "123456", "cardLastFour": "1234", "cardExpirationDate": null, "acquirerBin": null, "status": "OPEN", "statusCode": null, "ruleType": null, "ruleName": null, "installmentNumber": null, "pricingTier": null, "transactionTimeStamp": "2024-11-09T09:30:00.000Z", "merchantDescriptor": "SAMPLE STORE", "descriptorContact": null, "ethocaMerchantId": "ETH123456", "merchantId": "54321", "merchantOrderId": "ORDER-123", "merchantName": "Sample Merchant", "partnerId": null, "partnerName": null, "clientName": null, "caid": null, "mcc": "5411", "amount": "250.75", "currency": "EUR", "transactionType": "KEYED", "initiatedBy": "CARDHOLDER", "liability": "YES", "authCode": "ABC12345", "source": "BARCLAYS", "reasonCode": "UNAU", "acquirerReferenceNumber": "12345678901234567890123", "transactionId": "TRANS123456789", "chargebackAmount": null, "chargebackCurrency": null, "paymentType": null, "createdAt": "2024-11-10T19:07:56.293Z", "updatedAt": "2024-11-10T19:07:56.293Z", "expiredAt": null, "hasExternalTransaction": false, "outcome": null, "hoursLeft": 18 } ], "total": 1, "page": 0, "size": 10, "totalPages": 1 } ``` The `outcome` property is `null` until a resolution is recorded. The list response also includes `hoursLeft`, which is `0` after an outcome exists. ## Retrieve an alert by ID Returns one alert, including its current `outcome`. ### Endpoint `GET /api/v1/alerts/:id` ### Sample request ```bash theme={null} curl "https://api.trusto.io/api/v1/alerts/c8edf8a4-4e4d-4821-af34-9ed2995cbd8b" \ -H "X-API-KEY: YOUR_API_KEY" ``` ### Resolved alert response ```json theme={null} { "id": "c8edf8a4-4e4d-4821-af34-9ed2995cbd8b", "providerId": "6d9e6dc7-3cf7-4a9d-ae66-97bcf86b80d2", "provider": "ETHOCA", "type": "ETHOCA_CONFIRMED_FRAUD", "status": "RESOLVED", "amount": "250.75", "currency": "EUR", "hasExternalTransaction": false, "createdAt": "2024-11-10T19:07:56.293Z", "updatedAt": "2024-11-10T19:12:20.000Z", "outcome": { "id": "4a0c8f5d-4b8d-4f4d-8f1a-2f8c9c1e5b7b", "alertId": "c8edf8a4-4e4d-4821-af34-9ed2995cbd8b", "ethocaID": "6d9e6dc7-3cf7-4a9d-ae66-97bcf86b80d2", "status": "SUCCESS", "outcome": "other", "refunded": "refunded", "comments": "Customer issue resolved.", "disputeReasonCode": null, "actionTimestamp": "2024-11-10T19:12:20.000Z" } } ``` The example is abbreviated. Alert details use the same alert fields returned inside the list response. *** # Resolutions ## Provide an alert resolution Records a resolution for an unresolved alert and returns the updated alert with its nested `outcome`. ### Endpoint `PUT /api/v1/alerts/:id/resolution` ### Request headers | Header | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------- | | X-API-KEY | string | Yes | API key generated in Trusto. | | Content-Type | string | Yes | Must be `application/json`. | ### Path parameters | Parameter | Type | Description | | --------- | ---- | ---------------- | | id | UUID | Trusto alert ID. | ### Body parameters | Parameter | Type | Required | Description | | ---------- | -------------- | ------------- | ------------------------------------------------------------------------ | | refunded | string | Yes | Merchant decision: `REFUNDED`, `NOT REFUNDED`, or `INVALID`. | | resolution | string or null | For `INVALID` | Reason the alert is invalid. Omit it or send `null` for other decisions. | | comments | string | No | Free-form comments, up to 250 characters. | When `refunded` is `INVALID`, use one of these `resolution` values: | Resolution | Meaning | | ----------------------------------- | ----------------------------------------------- | | REFUNDED\_PREVIOUSLY\_REFUNDED | The transaction was refunded before this alert. | | NOT\_REFUNDED\_CHARGEBACK\_RECEIVED | A chargeback has already been received. | | NOT\_REFUNDED\_DUPLICATE | The alert is a duplicate. | | NOT\_REFUNDED\_NOT\_FOUND | The transaction could not be found. | ### Resolution results | refunded | resolution | Alert status | | ------------ | ----------------------------------- | ------------ | | REFUNDED | Omitted or `null` | RESOLVED | | NOT REFUNDED | Omitted or `null` | CHARGEBACK | | INVALID | REFUNDED\_PREVIOUSLY\_REFUNDED | INVALID | | INVALID | NOT\_REFUNDED\_CHARGEBACK\_RECEIVED | INVALID | | INVALID | NOT\_REFUNDED\_DUPLICATE | INVALID | | INVALID | NOT\_REFUNDED\_NOT\_FOUND | INVALID | ### Refunded request ```bash theme={null} curl -X PUT "https://api.trusto.io/api/v1/alerts/c8edf8a4-4e4d-4821-af34-9ed2995cbd8b/resolution" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "refunded": "REFUNDED", "resolution": null, "comments": "Customer issue resolved." }' ``` ### Invalid request ```json theme={null} { "refunded": "INVALID", "resolution": "NOT_REFUNDED_NOT_FOUND", "comments": "No matching transaction was found." } ``` ### Response A successful request returns the updated alert object. Its `status` reflects the decision, and its `outcome` contains the stored resolution details. A resolution submitted for an alert that already has an outcome returns a conflict error. Provider failures return a bad request error and the resolution is not retained. *** # Webhooks Webhooks enable organizations to receive event notifications about subscribed entities. ## Supported events | Event | Description | | -------------- | -------------------------------------- | | alert.created | Triggered when a new alert is created. | | alert.resolved | Triggered when an alert is resolved. | ## Webhook authentication Trusto can send either Basic Authentication or custom headers configured for the webhook endpoint. *** # Appendix ## Alert types * `ETHOCA_CONFIRMED_FRAUD` * `ETHOCA_CUSTOMER_DISPUTE` * `VERIFI_DISPUTE` * `VERIFI_CANCEL` * `VERIFI_DISPUTE_NOTICE` * `VERIFI_FRAUD_NOTICE` * `VERIFI_CANCEL_NOTICE` ## Alert outcome fields | Attribute | Type | Description | | ----------------- | -------------- | ----------------------------------------------------------------------- | | id | UUID | Outcome ID. | | alertId | UUID | Trusto alert ID. | | ethocaID | string | Provider alert ID. The legacy field name is retained for all providers. | | status | string | Outcome processing status, such as `SUCCESS`. | | outcome | string | Internal normalized outcome. | | refunded | string | Stored normalized refund decision. | | comments | string | Resolution comments. | | disputeReasonCode | string or null | Normalized invalid reason. | | actionTimestamp | string | Resolution timestamp in ISO 8601 format. |