Astrada transaction-matches API
Access transaction matches between bank and card transactions, including confidence scores and match reasoning.
OpenAPI Specification
openapi: 3.0.3
info:
title: Astrada bank-accounts transaction-matches API
version: '2024-02-28'
contact:
email: developer@astrada.co
description: 'Welcome to our API Reference. 👋
'
servers:
- url: https://api.astrada.co
security: null
tags:
- name: transaction-matches
description: Access transaction matches between bank and card transactions, including confidence scores and match reasoning.
paths:
/transaction-matches/{subaccountId}/{transactionMatchId}:
parameters:
- $ref: '#/components/parameters/subaccount-id-2'
- $ref: '#/components/parameters/transaction-match-id'
get:
tags:
- transaction-matches
summary: Retrieve transaction match
description: Returns detailed information about a specific transaction match, including the confidence level, numeric score, and a breakdown of the scoring factors.
operationId: GetTransactionMatch
security:
- main-auth:
- banking:read
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/transaction-match'
examples:
Example Get Transaction Match Response:
$ref: '#/components/examples/transaction-match'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
/transaction-matches/{subaccountId}:
parameters:
- $ref: '#/components/parameters/subaccount-id-2'
get:
tags:
- transaction-matches
summary: List transaction matches
description: 'Returns a list of transaction matches for a subaccount. Each match represents a link between a bank transaction and a card transaction, along with a confidence score and the reasoning behind the match.
By default, matches are filtered to `MEDIUM` confidence and above. Use the `minConfidence` parameter to adjust the threshold.
By default, `GET /transaction-matches/{subaccountId}` returns matches ordered by the latest `createdAt`.
This endpoint supports cursor-based pagination.
'
operationId: ListTransactionMatches
parameters:
- $ref: '#/components/parameters/bank-account-id-2'
- $ref: '#/components/parameters/card-id-2'
- $ref: '#/components/parameters/bank-transaction-id'
- $ref: '#/components/parameters/card-transaction-id'
- $ref: '#/components/parameters/min-confidence'
- $ref: '#/components/parameters/start-date'
- $ref: '#/components/parameters/end-date'
- $ref: '#/components/parameters/banking-limit'
- $ref: '#/components/parameters/cursor'
security:
- main-auth:
- banking:read
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
required:
- items
- pagination
properties:
items:
type: array
items:
$ref: '#/components/schemas/transaction-match'
pagination:
type: object
required:
- hasMore
properties:
cursor:
type: string
description: Cursor to use for the next page of results.
hasMore:
type: boolean
description: Whether there are more results available.
examples:
Example List Transaction Matches Response:
value:
items:
- _links:
self:
href: /transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
cardTransaction:
href: /transactions/a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d
bankTransaction:
href: /bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
id: b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
accountId: 8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
subaccountId: 1fcb895e-9217-4a6f-9d10-5a7dcef86c11
cardTransactionId: a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d
bankTransactionId: 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
confidence: HIGH
score: 0.85
cardTransaction:
date: '2025-10-15'
amount: 42.5
currency: USD
descriptor: UBER TRIP
bankTransaction:
date: '2025-10-15'
amount: 42.5
currency: USD
description: UBER TRIP
merchantName: Uber
reasons:
- type: Amount
score: 1
cardValue: '42.50'
bankValue: '42.50'
diff: 0
message: Exact amount match ($42.50)
- type: Date
score: 0.9
cardValue: '2025-10-15'
bankValue: '2025-10-15'
diff: 0
message: Transaction dates within 1 day
- type: Merchant
score: 0.85
cardValue: UBER TRIP
bankValue: Uber
diff: 0
message: Merchant name contains match (Uber)
createdAt: '2025-10-15T14:31:00.000Z'
pagination:
hasMore: false
links:
GetFirstTransactionMatch:
operationId: GetTransactionMatch
parameters:
transactionMatchId: $response.body#/items/0/id
description: Retrieve the first transaction match from the list.
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/server-error'
components:
parameters:
cursor:
in: query
name: cursor
required: false
description: The cursor to use for pagination. Identifies your place on the list
schema:
type: string
format: byte
example: ZXhhbXBsZQ==
card-transaction-id:
in: query
name: cardTransactionId
description: Filter by card transaction identifier
required: false
schema:
type: string
format: uuid
example: a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d
transaction-match-id:
in: path
name: transactionMatchId
required: true
schema:
type: string
format: uuid
example: c3d4e5f6-a7b8-9012-cdef-123456789012
start-date:
in: query
name: startDate
description: Filter results from this date (inclusive), in YYYY-MM-DD format
required: false
schema:
type: string
format: date
example: '2025-10-01'
card-id-2:
in: path
name: cardId
required: true
schema:
type: string
format: uuid
example: 6d18f5bb-b9d6-4237-97c2-44b1bdb71d6b
min-confidence:
in: query
name: minConfidence
description: Filter transaction matches by minimum confidence level. Defaults to `MEDIUM`, which returns HIGH and MEDIUM matches.
required: false
schema:
type: string
enum:
- HIGH
- MEDIUM
- LOW
default: MEDIUM
example: MEDIUM
bank-transaction-id:
in: query
name: bankTransactionId
description: Filter by bank transaction identifier
required: false
schema:
type: string
format: uuid
example: 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
bank-account-id-2:
in: query
name: bankAccountId
description: Filter by bank account identifier
required: false
schema:
type: string
format: uuid
example: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
banking-limit:
in: query
name: limit
description: Maximum number of items to return
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 250
example: 250
end-date:
in: query
name: endDate
description: Filter results up to this date (inclusive), in YYYY-MM-DD format
required: false
schema:
type: string
format: date
example: '2025-10-31'
subaccount-id-2:
in: path
name: subaccountId
required: true
schema:
type: string
format: uuid
example: 24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c
responses:
not-found:
description: The requested resource was not found on the server
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
instance:
type: string
detail:
type: string
title:
type: string
enum:
- Not Found
required:
- detail
- title
example:
title: Not Found
detail: The requested resource was not found on the server.
unauthorized:
description: Authentication credentials were either missing or incorrect
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Unauthorized
required:
- detail
- title
example:
title: Unauthorized
detail: Authentication credentials were either missing or incorrect.
forbidden:
description: Authentication credentials used do not have have permissions to perform the request
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Forbidden
required:
- detail
- title
example:
title: Forbidden
detail: You do not have permission to access the requested resource.
server-error:
description: The server encountered an unexpected condition that prevented it from fulfilling the request
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Internal Server Error
required:
- detail
- title
example:
title: Internal Server Error
detail: The server encountered an unexpected condition that prevented it from fulfilling the request.
schemas:
transaction-match:
type: object
required:
- _links
- id
- accountId
- subaccountId
- cardTransactionId
- bankTransactionId
- confidence
- score
- cardTransaction
- bankTransaction
- reasons
- createdAt
properties:
_links:
type: object
description: HAL-style links to related resources.
required:
- self
- cardTransaction
- bankTransaction
properties:
self:
$ref: '#/components/schemas/link'
cardTransaction:
$ref: '#/components/schemas/link'
bankTransaction:
$ref: '#/components/schemas/link'
card:
$ref: '#/components/schemas/link'
id:
type: string
format: uuid
description: The unique identifier of the transaction match.
accountId:
type: string
format: uuid
description: The unique identifier of the account that owns this match.
subaccountId:
type: string
format: uuid
description: The unique identifier of the subaccount associated with this match.
cardTransactionId:
type: string
format: uuid
description: The unique identifier of the matched card transaction.
bankTransactionId:
type: string
format: uuid
description: The unique identifier of the matched bank transaction.
confidence:
type: string
description: 'The confidence level of the match.
- `HIGH`: Score >= 0.70
- `MEDIUM`: Score >= 0.50
- `LOW`: Score >= 0.20
'
enum:
- HIGH
- MEDIUM
- LOW
score:
type: number
description: The numeric match score between 0 and 1, representing how closely the bank and card transactions match.
minimum: 0
maximum: 1
cardTransaction:
type: object
description: Summary of the matched card transaction.
properties:
cardId:
type: string
format: uuid
nullable: true
description: The card identifier associated with the matched card transaction.
date:
type: string
description: The transaction date.
amount:
type: number
description: The transaction amount.
currency:
type: string
description: The transaction currency.
descriptor:
type: string
description: The merchant descriptor.
bankTransaction:
type: object
description: Summary of the matched bank transaction.
properties:
date:
type: string
description: The transaction date.
amount:
type: number
description: The transaction amount.
currency:
type: string
description: The transaction currency.
description:
type: string
description: The transaction description.
merchantName:
type: string
nullable: true
description: The merchant name.
reasons:
type: array
description: Breakdown of the scoring factors that contributed to the match score.
items:
type: object
properties:
type:
type: string
description: The matching factor type.
enum:
- Amount
- Date
- Merchant
- ReferenceId
- PreAuth
score:
type: number
description: The individual score for this factor.
cardValue:
description: The value from the card transaction used for comparison. May be a string or numeric value.
type: string
nullable: true
bankValue:
description: The value from the bank transaction used for comparison. May be a string or numeric value.
type: string
nullable: true
diff:
type: number
description: The numeric difference between the card and bank values.
message:
type: string
description: Human-readable explanation of the score for this factor.
createdAt:
description: Date and time when this match was created, in UTC, following ISO 8601 format.
type: string
format: date-time
link:
type: object
properties:
href:
type: string
templated:
type: boolean
type:
type: string
deprecation:
type: string
name:
type: string
profile:
type: string
title:
type: string
hreflang:
type: string
required:
- href
examples:
transaction-match:
description: Example of a Transaction Match resource
value:
_links:
self:
href: /transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
cardTransaction:
href: /transaction-messages/a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d
bankTransaction:
href: /bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
card:
href: /cards/5dec2c49-0aa5-4683-a317-427eb5d115f3
id: b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
accountId: 8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
subaccountId: 1fcb895e-9217-4a6f-9d10-5a7dcef86c11
cardTransactionId: a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d
bankTransactionId: 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
confidence: HIGH
score: 0.85
cardTransaction:
cardId: 5dec2c49-0aa5-4683-a317-427eb5d115f3
date: '2025-10-15'
amount: 42.5
currency: USD
descriptor: UBER TRIP
bankTransaction:
date: '2025-10-15'
amount: 42.5
currency: USD
description: UBER TRIP
merchantName: Uber
reasons:
- type: Amount
score: 1
cardValue: '42.50'
bankValue: '42.50'
diff: 0
message: Exact amount match ($42.50)
- type: Date
score: 0.9
cardValue: '2025-10-15'
bankValue: '2025-10-15'
diff: 0
message: Transaction dates within 1 day
- type: Merchant
score: 0.85
cardValue: UBER TRIP
bankValue: Uber
diff: 0
message: Merchant name contains match (Uber)
createdAt: '2025-10-15T14:31:00.000Z'
securitySchemes:
main-auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
refreshUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
scopes:
accounts:write: Accounts write resource
accounts:read: Accounts read resource
subaccounts:write: Subaccounts write resource
subaccounts:read: Subaccounts read resource
card-connector-data-links:write: card-connector-data-link resource
card-connector-consents:read: Card Consent read resource
card-connector-consents:write: Card Consent write resource
webhooks:read: Read Webhook resources
webhooks:write: Write Webhook resources
card-subscriptions:write: Create card subscription
card-subscriptions:read: Read card subscription
card-verifications:write: Create card verification
card-verifications:read: Read Card verification
cards:read: Read Card resources
cardholder:read: Read Cardholder resources
cardholder:write: Write Cardholder resources
transactions:read: Read Transaction resources
transaction-messages:read: Read Transaction Message resources
network-bulk-feeds:read: Read network bulk feed
network-bulk-feeds:write: Write network bulk feed
network-links:write: Write network link
enrollment-methods:write: Write enrollment methods
simulation:write: Write sandbox simulations
banking:read: Read banking resources
banking:write: Write banking resources
banking:admin: Admin banking operations
appstore:enrollment:write: Enroll cards via the appstore B2C flow
appstore:cards:read: View enrolled cards in the appstore
appstore:transactions:read: View synced transactions in the appstore
appstore:transactions:sync: Trigger transaction sync in the appstore
appstore:sessions:read: Read appstore session state
appstore:sessions:write: Write or delete appstore session state
appstore:tokens:read: Read appstore stored tokens and connections
appstore:tokens:write: Write appstore stored tokens and connections
externalDocs:
description: Find out more about Astrada API.
url: https://docs.astrada.co/reference