{ "openapi": "3.0.3", "info": { "title": "Up API", "version": "v1", "description": "The Up API gives you programmatic access to your balances and\ntransaction data. You can request past transactions or set up\nwebhooks to receive real-time events when new transactions hit your\naccount. It’s new, it’s exciting and it’s just the beginning.\n", "contact": { "name": "API Specification and Support", "url": "https://github.com/up-banking/api" } }, "servers": [ { "url": "https://api.up.com.au/api/v1" } ], "components": { "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } }, "schemas": { "AccountTypeEnum": { "enum": ["SAVER", "TRANSACTIONAL", "HOME_LOAN"], "description": "Specifies the type of bank account. Currently returned values are\n`SAVER`, `TRANSACTIONAL` and `HOME_LOAN`.\n" }, "OwnershipTypeEnum": { "enum": ["INDIVIDUAL", "JOINT"], "description": "Specifies the structure under which a bank account is owned. Currently\nreturned values are `INDIVIDUAL` and `JOINT`.\n" }, "MoneyObject": { "type": "object", "description": "Provides information about a value of money.\n", "properties": { "currencyCode": { "type": "string", "description": "The ISO 4217 currency code.\n" }, "value": { "type": "string", "description": "The amount of money, formatted as a string in the relevant currency.\nFor example, for an Australian dollar value of $10.56, this field will\nbe `\"10.56\"`. The currency symbol is not included in the string.\n" }, "valueInBaseUnits": { "type": "integer", "description": "The amount of money in the smallest denomination for the currency, as a\n64-bit integer. For example, for an Australian dollar value of $10.56,\nthis field will be `1056`.\n" } }, "required": ["currencyCode", "value", "valueInBaseUnits"] }, "AccountResource": { "type": "object", "description": "Provides information about an Up bank account.\n", "properties": { "type": { "type": "string", "description": "The type of this resource: `accounts`" }, "id": { "type": "string", "description": "The unique identifier for this account.\n" }, "attributes": { "type": "object", "properties": { "displayName": { "type": "string", "description": "The name associated with the account in the Up application.\n" }, "accountType": { "description": "The bank account type of this account.\n", "allOf": [ { "$ref": "#/components/schemas/AccountTypeEnum" } ] }, "ownershipType": { "description": "The ownership structure for this account.\n", "allOf": [ { "$ref": "#/components/schemas/OwnershipTypeEnum" } ] }, "balance": { "description": "The available balance of the account, taking into account any amounts\nthat are currently on hold.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyObject" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "The date-time at which this account was first opened.\n" } }, "required": [ "displayName", "accountType", "ownershipType", "balance", "createdAt" ] }, "relationships": { "type": "object", "properties": { "transactions": { "type": "object", "properties": { "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } } } }, "required": ["transactions"] }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "The canonical link to this resource within the API.\n" } }, "required": ["self"] } }, "required": ["type", "id", "attributes", "relationships"] }, "ListAccountsResponse": { "type": "object", "description": "Successful response to get all accounts. This returns a paginated list of\naccounts, which can be scrolled by following the `prev` and `next` links\nif present.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountResource" }, "description": "The list of accounts returned in this response.\n" }, "links": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "description": "The link to the previous page in the results. If this value is `null`\nthere is no previous page.\n" }, "next": { "type": "string", "nullable": true, "description": "The link to the next page in the results. If this value is `null`\nthere is no next page.\n" } }, "required": ["prev", "next"] } }, "required": ["data", "links"] }, "GetAccountResponse": { "type": "object", "description": "Successful response to get a single account.\n", "properties": { "data": { "description": "The account returned in this response.\n", "allOf": [ { "$ref": "#/components/schemas/AccountResource" } ] } }, "required": ["data"] }, "AttachmentResource": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `attachments`" }, "id": { "type": "string", "description": "The unique identifier for this attachment.\n" }, "attributes": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "The date-time when the file was created.\n" }, "fileURL": { "type": "string", "nullable": true, "description": "A temporary link to download the file.\n" }, "fileURLExpiresAt": { "type": "string", "format": "date-time", "description": "The date-time at which the `fileURL` link expires.\n" }, "fileExtension": { "type": "string", "nullable": true, "description": "File extension for the uploaded attachment.\n" }, "fileContentType": { "type": "string", "nullable": true, "description": "Content type for the uploaded attachment.\n" } }, "required": [ "createdAt", "fileURL", "fileURLExpiresAt", "fileExtension", "fileContentType" ] }, "relationships": { "type": "object", "properties": { "transaction": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `transactions`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"] }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"] } }, "required": ["transaction"] }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "The canonical link to this resource within the API.\n" } }, "required": ["self"] } }, "required": ["type", "id", "attributes", "relationships"] }, "ListAttachmentsResponse": { "type": "object", "description": "Successful response to get all attachments. This returns a paginated list of\nattachments, which can be scrolled by following the `prev` and `next` links if\npresent.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentResource" }, "description": "The list of attachments returned in this response.\n" }, "links": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "description": "The link to the previous page in the results. If this value is `null`\nthere is no previous page.\n" }, "next": { "type": "string", "nullable": true, "description": "The link to the next page in the results. If this value is `null`\nthere is no next page.\n" } }, "required": ["prev", "next"] } }, "required": ["data", "links"] }, "GetAttachmentResponse": { "type": "object", "description": "Successful response to get a single attachment.\n", "properties": { "data": { "description": "The attachment returned in this response.\n", "allOf": [ { "$ref": "#/components/schemas/AttachmentResource" } ] } }, "required": ["data"] }, "CategoryResource": { "type": "object", "description": "Provides information about a category and its ancestry.\n", "properties": { "type": { "type": "string", "description": "The type of this resource: `categories`" }, "id": { "type": "string", "description": "The unique identifier for this category. This is a human-readable but\nURL-safe value.\n" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of this category as seen in the Up application.\n" } }, "required": ["name"] }, "relationships": { "type": "object", "properties": { "parent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `categories`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"], "nullable": true }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"] }, "children": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `categories`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"] } }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"] } }, "required": ["parent", "children"] }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "The canonical link to this resource within the API.\n" } }, "required": ["self"] } }, "required": ["type", "id", "attributes", "relationships"] }, "ListCategoriesResponse": { "type": "object", "description": "Successful response to get all categories and their ancestry. The\nreturned list is not paginated.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryResource" }, "description": "The list of categories returned in this response.\n" } }, "required": ["data"] }, "GetCategoryResponse": { "type": "object", "description": "Successful response to get a single category and its ancestry.\n", "properties": { "data": { "description": "The category returned in this response.\n", "allOf": [ { "$ref": "#/components/schemas/CategoryResource" } ] } }, "required": ["data"] }, "CategoryInputResourceIdentifier": { "type": "object", "description": "Uniquely identifies a category in the API.\n", "properties": { "type": { "type": "string", "description": "The type of this resource: `categories`" }, "id": { "type": "string", "description": "The unique identifier of the category, as returned by the `/categories`\nendpoint.\n" } }, "required": ["type", "id"] }, "UpdateTransactionCategoryRequest": { "type": "object", "description": "Request to update the category associated with a transaction.\n", "properties": { "data": { "nullable": true, "description": "The category to set on the transaction. Set this entire key to `null`\nde-categorize a transaction.\n", "allOf": [ { "$ref": "#/components/schemas/CategoryInputResourceIdentifier" } ] } }, "required": ["data"] }, "PingResponse": { "type": "object", "description": "Basic ping response to verify authentication.\n", "properties": { "meta": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the authenticated customer.\n" }, "statusEmoji": { "type": "string", "description": "A cute emoji that represents the response status.\n" } }, "required": ["id", "statusEmoji"] } }, "required": ["meta"] }, "ErrorObject": { "type": "object", "description": "Provides information about an error processing a request.\n", "properties": { "status": { "type": "string", "description": "The HTTP status code associated with this error. This can also be\nobtained from the response headers. The status indicates the broad type\nof error according to HTTP semantics.\n" }, "title": { "type": "string", "description": "A short description of this error. This should be stable across\nmultiple occurrences of this type of error and typically expands on the\nreason for the status code.\n" }, "detail": { "type": "string", "description": "A detailed description of this error. This should be considered unique\nto individual occurrences of an error and subject to change. It is\nuseful for debugging purposes.\n" }, "source": { "type": "object", "properties": { "parameter": { "type": "string", "description": "If this error relates to a query parameter, the name of the\nparameter.\n" }, "pointer": { "type": "string", "description": "If this error relates to an attribute in the request body, a\nrfc-6901 JSON pointer to the attribute.\n" } }, "description": "If applicable, location in the request that this error relates to. This\nmay be a parameter in the query string, or a an attribute in the\nrequest body.\n" } }, "required": ["status", "title", "detail"] }, "ErrorResponse": { "type": "object", "description": "Generic error response that returns one or more errors.\n", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorObject" }, "description": "The list of errors returned in this response.\n" } }, "required": ["errors"] }, "TagResource": { "type": "object", "description": "Provides information about a tag.\n", "properties": { "type": { "type": "string", "description": "The type of this resource: `tags`" }, "id": { "type": "string", "description": "The label of the tag, which also acts as the tag’s unique identifier.\n" }, "relationships": { "type": "object", "properties": { "transactions": { "type": "object", "properties": { "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } } } }, "required": ["transactions"] } }, "required": ["type", "id", "relationships"] }, "ListTagsResponse": { "type": "object", "description": "Successful response to get all tags. This returns a paginated list of\ntags, which can be scrolled by following the `prev` and `next` links if\npresent.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TagResource" }, "description": "The list of tags returned in this response.\n" }, "links": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "description": "The link to the previous page in the results. If this value is `null`\nthere is no previous page.\n" }, "next": { "type": "string", "nullable": true, "description": "The link to the next page in the results. If this value is `null`\nthere is no next page.\n" } }, "required": ["prev", "next"] } }, "required": ["data", "links"] }, "TagInputResourceIdentifier": { "type": "object", "description": "Uniquely identifies a single tag in the API.\n", "properties": { "type": { "type": "string", "description": "The type of this resource: `tags`" }, "id": { "type": "string", "description": "The label of the tag, which also acts as the tag’s unique identifier.\n" } }, "required": ["type", "id"] }, "UpdateTransactionTagsRequest": { "type": "object", "description": "Request to add or remove tags associated with a transaction.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TagInputResourceIdentifier" }, "description": "The tags to add to or remove from the transaction.\n" } }, "required": ["data"] }, "TransactionStatusEnum": { "enum": ["HELD", "SETTLED"], "description": "Specifies which stage of processing a transaction is currently at.\nCurrently returned values are `HELD` and `SETTLED`. When a transaction is\nheld, its account’s `availableBalance` is affected. When a transaction is\nsettled, its account’s `currentBalance` is affected.\n" }, "HoldInfoObject": { "type": "object", "description": "Provides information about the amount at which a transaction was in the\n`HELD` status.\n", "properties": { "amount": { "description": "The amount of this transaction while in the `HELD` status, in\nAustralian dollars.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyObject" } ] }, "foreignAmount": { "nullable": true, "description": "The foreign currency amount of this transaction while in the `HELD`\nstatus. This field will be `null` for domestic transactions. The amount\nwas converted to the AUD amount reflected in the `amount` field.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyObject" } ] } }, "required": ["amount", "foreignAmount"] }, "RoundUpObject": { "type": "object", "description": "Provides information about how a Round Up was applied, such as whether or\nnot a boost was included in the Round Up.\n", "properties": { "amount": { "description": "The total amount of this Round Up, including any boosts, represented as\na negative value.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyObject" } ] }, "boostPortion": { "nullable": true, "description": "The portion of the Round Up `amount` owing to boosted Round Ups,\nrepresented as a negative value. If no boost was added to the Round Up\nthis field will be `null`.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyObject" } ] } }, "required": ["amount", "boostPortion"] }, "CashbackObject": { "type": "object", "description": "Provides information about an instant reimbursement in the form of\ncashback.\n", "properties": { "description": { "type": "string", "description": "A brief description of why this cashback was paid.\n" }, "amount": { "description": "The total amount of cashback paid, represented as a positive value.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyObject" } ] } }, "required": ["description", "amount"] }, "CardPurchaseMethodEnum": { "enum": [ "BAR_CODE", "OCR", "CARD_PIN", "CARD_DETAILS", "CARD_ON_FILE", "ECOMMERCE", "MAGNETIC_STRIPE", "CONTACTLESS" ], "description": "Specifies the type of card charge.\n" }, "CardPurchaseMethodObject": { "type": "object", "description": "Provides information about the card used for a transaction.\n", "properties": { "method": { "description": "The type of card purchase.\n", "allOf": [ { "$ref": "#/components/schemas/CardPurchaseMethodEnum" } ] }, "cardNumberSuffix": { "type": "string", "nullable": true, "description": "The last four digits of the card used for the purchase, if applicable.\n" } }, "required": ["method", "cardNumberSuffix"] }, "NoteObject": { "type": "object", "description": "Provides information about the note and attachement.\n", "properties": { "text": { "type": "string", "description": "A text note about the transaction.\n" } }, "required": ["text"] }, "CustomerObject": { "type": "object", "description": "Provides information about the customer who initiated a transaction\n", "properties": { "displayName": { "type": "string", "description": "The Upname or preferred name of the customer\n" } }, "required": ["displayName"] }, "TransactionResource": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `transactions`" }, "id": { "type": "string", "description": "The unique identifier for this transaction.\n" }, "attributes": { "type": "object", "properties": { "status": { "description": "The current processing status of this transaction, according to\nwhether or not this transaction has settled or is still held.\n", "allOf": [ { "$ref": "#/components/schemas/TransactionStatusEnum" } ] }, "rawText": { "type": "string", "nullable": true, "description": "The original, unprocessed text of the transaction. This is often not\na perfect indicator of the actual merchant, but it is useful for\nreconciliation purposes in some cases.\n" }, "description": { "type": "string", "description": "A short description for this transaction. Usually the merchant name\nfor purchases.\n" }, "message": { "type": "string", "nullable": true, "description": "Attached message for this transaction, such as a payment message, or a\ntransfer note.\n" }, "isCategorizable": { "type": "boolean", "description": "Boolean flag set to true on transactions that support the use of\ncategories.\n" }, "holdInfo": { "nullable": true, "description": "If this transaction is currently in the `HELD` status, or was ever in\nthe `HELD` status, the `amount` and `foreignAmount` of the\ntransaction while `HELD`.\n", "allOf": [ { "$ref": "#/components/schemas/HoldInfoObject" } ] }, "roundUp": { "nullable": true, "description": "Details of how this transaction was rounded-up. If no Round Up was\napplied this field will be `null`.\n", "allOf": [ { "$ref": "#/components/schemas/RoundUpObject" } ] }, "cashback": { "nullable": true, "description": "If all or part of this transaction was instantly reimbursed in the\nform of cashback, details of the reimbursement.\n", "allOf": [ { "$ref": "#/components/schemas/CashbackObject" } ] }, "amount": { "description": "The amount of this transaction in Australian dollars. For\ntransactions that were once `HELD` but are now `SETTLED`, refer to\nthe `holdInfo` field for the original `amount` the transaction was\n`HELD` at.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyObject" } ] }, "foreignAmount": { "nullable": true, "description": "The foreign currency amount of this transaction. This field will be\n`null` for domestic transactions. The amount was converted to the AUD\namount reflected in the `amount` of this transaction. Refer to the\n`holdInfo` field for the original `foreignAmount` the transaction was\n`HELD` at.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyObject" } ] }, "cardPurchaseMethod": { "nullable": true, "description": "Information about the card used for this transaction, if applicable.\n", "allOf": [ { "$ref": "#/components/schemas/CardPurchaseMethodObject" } ] }, "settledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "The date-time at which this transaction settled. This field will be\n`null` for transactions that are currently in the `HELD` status.\n" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date-time at which this transaction was first encountered.\n" }, "transactionType": { "type": "string", "nullable": true, "description": "A description of the transaction method used e.g. Purchase, BPAY Payment.\n" }, "note": { "nullable": true, "description": "A customer provided note about the transaction. Can only be provided by Up High subscribers.\n", "allOf": [ { "$ref": "#/components/schemas/NoteObject" } ] }, "performingCustomer": { "nullable": true, "description": "The customer who initated the transaction. For 2Up accounts this could be the customer who's card was used.\n", "allOf": [ { "$ref": "#/components/schemas/CustomerObject" } ] } }, "required": [ "status", "rawText", "description", "message", "isCategorizable", "holdInfo", "roundUp", "cashback", "amount", "foreignAmount", "cardPurchaseMethod", "settledAt", "createdAt", "transactionType", "note", "performingCustomer" ] }, "relationships": { "type": "object", "properties": { "account": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `accounts`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"] }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"] }, "transferAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `accounts`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"], "nullable": true }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"], "description": "If this transaction is a transfer between accounts, this relationship\nwill contain the account the transaction went to/came from. The\n`amount` field can be used to determine the direction of the transfer.\n" }, "category": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `categories`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"], "nullable": true }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "The link to retrieve or modify linkage between this resources and the\nrelated resource(s) in this relationship.\n" }, "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["self"] } }, "required": ["data"] }, "parentCategory": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `categories`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"], "nullable": true }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"] }, "tags": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `tags`" }, "id": { "type": "string", "description": "The label of the tag, which also acts as the tag’s unique identifier.\n" } }, "required": ["type", "id"] } }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "The link to retrieve or modify linkage between this resources and the\nrelated resource(s) in this relationship.\n" } }, "required": ["self"] } }, "required": ["data"] }, "attachment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `attachments`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"], "nullable": true }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"] } }, "required": [ "account", "transferAccount", "category", "parentCategory", "tags", "attachment" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "The canonical link to this resource within the API.\n" } }, "required": ["self"] } }, "required": ["type", "id", "attributes", "relationships"] }, "ListTransactionsResponse": { "type": "object", "description": "Successful response to get all transactions. This returns a paginated\nlist of transactions, which can be scrolled by following the `prev` and\n`next` links if present.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionResource" }, "description": "The list of transactions returned in this response.\n" }, "links": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "description": "The link to the previous page in the results. If this value is `null`\nthere is no previous page.\n" }, "next": { "type": "string", "nullable": true, "description": "The link to the next page in the results. If this value is `null`\nthere is no next page.\n" } }, "required": ["prev", "next"] } }, "required": ["data", "links"] }, "GetTransactionResponse": { "type": "object", "description": "Successful response to get a single transaction.\n", "properties": { "data": { "description": "The transaction returned in this response.\n", "allOf": [ { "$ref": "#/components/schemas/TransactionResource" } ] } }, "required": ["data"] }, "WebhookResource": { "type": "object", "description": "Provides information about a webhook.\n", "properties": { "type": { "type": "string", "description": "The type of this resource: `webhooks`" }, "id": { "type": "string", "description": "The unique identifier for this webhook.\n" }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL that this webhook is configured to `POST` events to.\n" }, "description": { "type": "string", "nullable": true, "description": "An optional description that was provided at the time the webhook was\ncreated.\n" }, "secretKey": { "type": "string", "description": "A shared secret key used to sign all webhook events sent to the\nconfigured webhook URL. This field is returned only once, upon the\ninitial creation of the webhook. If lost, create a new webhook and\ndelete this webhook.\n\nThe webhook URL receives a request with a\n`X-Up-Authenticity-Signature` header, which is the SHA-256 HMAC of\nthe entire raw request body signed using this `secretKey`. It is\nadvised to compute and check this signature to verify the\nauthenticity of requests sent to the webhook URL. See\n[Handling webhook events](#callback_post_webhookURL) for full\ndetails.\n" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date-time at which this webhook was created.\n" } }, "required": ["url", "description", "createdAt"] }, "relationships": { "type": "object", "properties": { "logs": { "type": "object", "properties": { "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } } } }, "required": ["logs"] }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "The canonical link to this resource within the API.\n" } }, "required": ["self"] } }, "required": ["type", "id", "attributes", "relationships"] }, "ListWebhooksResponse": { "type": "object", "description": "Successful response to get all webhooks. This returns a paginated list of\nwebhooks, which can be scrolled by following the `prev` and `next` links\nif present.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResource" }, "description": "The list of webhooks returned in this response.\n" }, "links": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "description": "The link to the previous page in the results. If this value is `null`\nthere is no previous page.\n" }, "next": { "type": "string", "nullable": true, "description": "The link to the next page in the results. If this value is `null`\nthere is no next page.\n" } }, "required": ["prev", "next"] } }, "required": ["data", "links"] }, "WebhookInputResource": { "type": "object", "description": "Represents a webhook specified as request input.\n", "properties": { "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL that this webhook should post events to. This must be a valid\nHTTP or HTTPS URL that does not exceed 300 characters in length.\n" }, "description": { "type": "string", "nullable": true, "description": "An optional description for this webhook, up to 64 characters in\nlength.\n" } }, "required": ["url"] } }, "required": ["attributes"] }, "CreateWebhookRequest": { "type": "object", "description": "Request to create a new webhook. This currently only requires a `url`\nattribute.\n", "properties": { "data": { "description": "The webhook resource to create.\n", "allOf": [ { "$ref": "#/components/schemas/WebhookInputResource" } ] } }, "required": ["data"] }, "CreateWebhookResponse": { "type": "object", "description": "Successful response after creating a webhook.\n", "properties": { "data": { "description": "The webhook that was created.\n", "allOf": [ { "$ref": "#/components/schemas/WebhookResource" } ] } }, "required": ["data"] }, "WebhookEventTypeEnum": { "enum": [ "TRANSACTION_CREATED", "TRANSACTION_SETTLED", "TRANSACTION_DELETED", "PING" ], "description": "Specifies the type of a webhook event. This can be used to determine what\naction to take in response to the event, such as which relationships to\nexpect.\n" }, "WebhookEventResource": { "type": "object", "description": "Provides the event data used in asynchronous webhook event callbacks to\nsubscribed endpoints. Webhooks events have defined `eventType`s and may\noptionally relate to other resources within the Up API.\n", "properties": { "type": { "type": "string", "description": "The type of this resource: `webhook-events`" }, "id": { "type": "string", "description": "The unique identifier for this event. This will remain constant across\ndelivery retries.\n" }, "attributes": { "type": "object", "properties": { "eventType": { "description": "The type of this event. This can be used to determine what action to\ntake in response to the event.\n", "allOf": [ { "$ref": "#/components/schemas/WebhookEventTypeEnum" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "The date-time at which this event was generated.\n" } }, "required": ["eventType", "createdAt"] }, "relationships": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `webhooks`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"] }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"] }, "transaction": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `transactions`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"] }, "links": { "type": "object", "properties": { "related": { "type": "string", "description": "The link to retrieve the related resource(s) in this relationship.\n" } }, "required": ["related"] } }, "required": ["data"] } }, "required": ["webhook"] } }, "required": ["type", "id", "attributes", "relationships"] }, "WebhookEventCallback": { "type": "object", "description": "Asynchronous callback request used for webhook event delivery.\n", "properties": { "data": { "description": "The webhook event data sent to the subscribed webhook.\n", "allOf": [ { "$ref": "#/components/schemas/WebhookEventResource" } ] } }, "required": ["data"] }, "GetWebhookResponse": { "type": "object", "description": "Successful response to get a single webhook.\n", "properties": { "data": { "description": "The webhook returned in this response.\n", "allOf": [ { "$ref": "#/components/schemas/WebhookResource" } ] } }, "required": ["data"] }, "WebhookDeliveryStatusEnum": { "enum": ["DELIVERED", "UNDELIVERABLE", "BAD_RESPONSE_CODE"], "description": "Specifies the nature of the success or failure of a webhook delivery\nattempt to the subscribed webhook URL. The currently returned values are\ndescribed below:\n\n- **`DELIVERED`**: The event was delivered to the webhook URL\n successfully and a `200` response was received.\n- **`UNDELIVERABLE`**: The webhook URL was not reachable, or timed out.\n- **`BAD_RESPONSE_CODE`**: The event was delivered to the webhook URL\n but a non-`200` response was received.\n" }, "WebhookDeliveryLogResource": { "type": "object", "description": "Provides historical webhook event delivery information for analysis and\ndebugging purposes.\n", "properties": { "type": { "type": "string", "description": "The type of this resource: `webhook-delivery-logs`" }, "id": { "type": "string", "description": "The unique identifier for this log entry.\n" }, "attributes": { "type": "object", "properties": { "request": { "type": "object", "properties": { "body": { "type": "string", "description": "The payload that was sent in the request body.\n" } }, "required": ["body"], "description": "Information about the request that was sent to the webhook URL.\n" }, "response": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "The HTTP status code received in the response.\n" }, "body": { "type": "string", "description": "The payload that was received in the response body.\n" } }, "required": ["statusCode", "body"], "nullable": true, "description": "Information about the response that was received from the webhook URL.\n" }, "deliveryStatus": { "description": "The success or failure status of this delivery attempt.\n", "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryStatusEnum" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "The date-time at which this log entry was created.\n" } }, "required": ["request", "response", "deliveryStatus", "createdAt"] }, "relationships": { "type": "object", "properties": { "webhookEvent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of this resource: `webhook-events`" }, "id": { "type": "string", "description": "The unique identifier of the resource within its type.\n" } }, "required": ["type", "id"] } }, "required": ["data"] } }, "required": ["webhookEvent"] } }, "required": ["type", "id", "attributes", "relationships"] }, "ListWebhookDeliveryLogsResponse": { "type": "object", "description": "Successful response to get all delivery logs for a webhook. This returns\na paginated list of delivery logs, which can be scrolled by following the\n`next` and `prev` links if present.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryLogResource" }, "description": "The list of delivery logs returned in this response.\n" }, "links": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "description": "The link to the previous page in the results. If this value is `null`\nthere is no previous page.\n" }, "next": { "type": "string", "nullable": true, "description": "The link to the next page in the results. If this value is `null`\nthere is no next page.\n" } }, "required": ["prev", "next"] } }, "required": ["data", "links"] } } }, "security": [ { "bearer_auth": [] } ], "tags": [ { "name": "Accounts", "description": "Accounts represent the underlying store used to track balances\nand the transactions that have occurred to modify those balances\nover time. Up currently has three types of account: `SAVER`—used to\nearn interest and to hit savings goals, `TRANSACTIONAL`—used\nfor everyday spending, and `HOME_LOAN`-for those with an Up Home loan.\n" }, { "name": "Categories", "description": "Categories enable understanding where your money goes by driving\npowerful insights in Up. All categories in Up are pre-defined\nand are automatically assigned to new purchases in most cases. A\nparent-child relationship is used to represent categories,\nhowever parent categories cannot be directly assigned to\ntransactions.\n" }, { "name": "Tags", "description": "Tags are custom labels that can be associated with transactions\non Up. Within the Up application, tags provide additional insight\ninto spending. For example, you could have a \"Take Away\" tag that\nyou apply to purchases from food delivery services. The Up API\nallows you to manage the tags associated with transactions. Each\ntransaction may have up to 6 tags.\n\nTags are identified by their labels, which are unique strings,\nso the tag \"Holiday\" has also the `id` `\"Holiday\"`.\n" }, { "name": "Transactions", "description": "Transactions represent the movement of money into and out of an\naccount. They have many characteristics that vary depending on\nthe kind of transaction. Transactions may be temporarily `HELD`\n(pending) or `SETTLED`, typically depending on which payment\nmethod was used at the point of sale.\n" }, { "name": "Attachments", "description": "Attachments represent uploaded files that are attached to transactions, these are commonly receipts.\n" }, { "name": "Utility endpoints", "description": "Some endpoints exist not to expose data, but to test the API\nitself. Currently there is only one endpoint in this group: ping!\n" }, { "name": "Webhooks", "description": "Webhooks provide a mechanism for a configured URL to receive\nevents when transaction activity occurs on Up. You can think of\nwebhooks as being like push notifications for your server-side\napplication.\n" } ], "paths": { "/accounts": { "get": { "tags": ["Accounts"], "summary": "List accounts", "description": "Retrieve a paginated list of all accounts for the currently\nauthenticated user. The returned list is paginated and can be scrolled\nby following the `prev` and `next` links where present.\n", "parameters": [ { "name": "page[size]", "in": "query", "schema": { "type": "integer" }, "required": false, "example": 30, "description": "The number of records to return in each page.\n" }, { "name": "filter[accountType]", "in": "query", "schema": { "$ref": "#/components/schemas/AccountTypeEnum" }, "required": false, "example": "SAVER", "description": "The type of account for which to return records. This\ncan be used to filter Savers from spending accounts.\n" }, { "name": "filter[ownershipType]", "in": "query", "schema": { "$ref": "#/components/schemas/OwnershipTypeEnum" }, "required": false, "example": "INDIVIDUAL", "description": "The account ownership structure for which to return\nrecords. This can be used to filter 2Up accounts from Up\naccounts.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccountsResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:z4qtHErGAZuuouwl" }, "pathParameters": {}, "queryParameters": { "page[size]": 1 }, "payload": null }, "response": { "data": [ { "type": "accounts", "id": "5b54e6ef-ecf1-4c49-aa03-2104a490c849", "attributes": { "displayName": "Spending", "accountType": "TRANSACTIONAL", "ownershipType": "INDIVIDUAL", "balance": { "currencyCode": "AUD", "value": "1.00", "valueInBaseUnits": 100 }, "createdAt": "2024-08-06T12:18:29+10:00" }, "relationships": { "transactions": { "links": { "related": "https://api.up.com.au/api/v1/accounts/5b54e6ef-ecf1-4c49-aa03-2104a490c849/transactions" } } }, "links": { "self": "https://api.up.com.au/api/v1/accounts/5b54e6ef-ecf1-4c49-aa03-2104a490c849" } } ], "links": { "prev": null, "next": "https://api.up.com.au/api/v1/accounts?page%5Bafter%5D=WyIyMDI0LTA4LTA2VDAyOjE4OjI5LjMwMzgzOTAwMFoiLCI1YjU0ZTZlZi1lY2YxLTRjNDktYWEwMy0yMTA0YTQ5MGM4NDkiXQ%3D%3D&page%5Bsize%5D=1" } } } } } } }, "/accounts/{id}": { "get": { "tags": ["Accounts"], "summary": "Retrieve account", "description": "Retrieve a specific account by providing its unique identifier.\n", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "7699cfe5-eabd-4855-bbe7-9dfe3f70cebf", "description": "The unique identifier for the account.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAccountResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:dvJloDOxw0NWMnzk" }, "pathParameters": { "id": "e647dd54-4d10-41d0-8071-21eb0a3f6214" }, "queryParameters": {}, "payload": null }, "response": { "data": { "type": "accounts", "id": "e647dd54-4d10-41d0-8071-21eb0a3f6214", "attributes": { "displayName": "🐷 Savings", "accountType": "SAVER", "ownershipType": "INDIVIDUAL", "balance": { "currencyCode": "AUD", "value": "125.36", "valueInBaseUnits": 12536 }, "createdAt": "2024-08-06T12:18:30+10:00" }, "relationships": { "transactions": { "links": { "related": "https://api.up.com.au/api/v1/accounts/e647dd54-4d10-41d0-8071-21eb0a3f6214/transactions" } } }, "links": { "self": "https://api.up.com.au/api/v1/accounts/e647dd54-4d10-41d0-8071-21eb0a3f6214" } } } } } } } }, "/attachments": { "get": { "tags": ["Attachments"], "summary": "List attachments", "description": "Retrieve a list of all attachments. The returned list is [paginated](#pagination) and can\nbe scrolled by following the `next` and `prev` links where present.\n", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAttachmentsResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:cV5W9g033vq1tYZ4" }, "pathParameters": {}, "queryParameters": {}, "payload": null }, "response": { "data": [ { "type": "attachments", "id": "23bc06a0-cff4-40ae-bcb3-463fac19b5b0", "attributes": { "createdAt": "2024-08-06T12:18:31+10:00", "fileURL": "http://localhost:8080/asset/customer_transaction_attachment.jpg?filename=uploads%2Fcustomer_transaction_attachments%2Fmodels%2Fattachment%2Ffile%2F1%2Fattachment.jpg×tamp=1722910712&token=881b77d17579aa98214271fc29a3e4b4438b937e0e818b0f543fdb5bd921822c", "fileURLExpiresAt": "2024-08-06T12:33:32+10:00", "fileExtension": "jpg", "fileContentType": "image/jpeg" }, "relationships": { "transaction": { "data": { "type": "transactions", "id": "9dd0a25a-c5ca-46c6-8e07-420274d5e8fe" }, "links": { "related": "https://api.up.com.au/api/v1/transactions/9dd0a25a-c5ca-46c6-8e07-420274d5e8fe" } } }, "links": { "self": "https://api.up.com.au/api/v1/attachments/23bc06a0-cff4-40ae-bcb3-463fac19b5b0" } }, { "type": "attachments", "id": "86f6e316-691e-48a6-b896-331362bb9b52", "attributes": { "createdAt": "2024-08-06T12:18:31+10:00", "fileURL": "http://localhost:8080/asset/customer_transaction_attachment.jpg?filename=uploads%2Fcustomer_transaction_attachments%2Fmodels%2Fattachment%2Ffile%2F2%2Fattachment.jpg×tamp=1722910712&token=a775955e0ae11f61b453dbdc9bd6d06b303a3aa4e6abacdcd1def8e4f8351559", "fileURLExpiresAt": "2024-08-06T12:33:32+10:00", "fileExtension": "jpg", "fileContentType": "image/jpeg" }, "relationships": { "transaction": { "data": { "type": "transactions", "id": "40390cc7-8c76-422f-b2a0-7a22c7d1c915" }, "links": { "related": "https://api.up.com.au/api/v1/transactions/40390cc7-8c76-422f-b2a0-7a22c7d1c915" } } }, "links": { "self": "https://api.up.com.au/api/v1/attachments/86f6e316-691e-48a6-b896-331362bb9b52" } } ], "links": { "prev": null, "next": null } } } } } } }, "/attachments/{id}": { "get": { "tags": ["Attachments"], "summary": "Retrieve attachment", "description": "Retrieve a specific attachment by providing its unique identifier.\n", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "3672d7fb-e56d-4c4a-b546-7c11ddb5e5e7", "description": "The unique identifier for the attachment.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAttachmentResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:lfQuAyww8UOTKTD4" }, "pathParameters": { "id": "4fcb7c00-5332-41bb-ae5a-26b66dda316b" }, "queryParameters": {}, "payload": null }, "response": { "data": { "type": "attachments", "id": "4fcb7c00-5332-41bb-ae5a-26b66dda316b", "attributes": { "createdAt": "2024-08-06T12:18:33+10:00", "fileURL": "http://localhost:8080/asset/customer_transaction_attachment.jpg?filename=uploads%2Fcustomer_transaction_attachments%2Fmodels%2Fattachment%2Ffile%2F5%2Fattachment.jpg×tamp=1722910713&token=3abc7139ebfbcaee1dc8a37d5bf0bc7d02334857919d7ce6695629bf340afbad", "fileURLExpiresAt": "2024-08-06T12:33:33+10:00", "fileExtension": "jpg", "fileContentType": "image/jpeg" }, "relationships": { "transaction": { "data": { "type": "transactions", "id": "b416028a-9c12-4716-a759-94913fe4dd49" }, "links": { "related": "https://api.up.com.au/api/v1/transactions/b416028a-9c12-4716-a759-94913fe4dd49" } } }, "links": { "self": "https://api.up.com.au/api/v1/attachments/4fcb7c00-5332-41bb-ae5a-26b66dda316b" } } } } } } } }, "/categories": { "get": { "tags": ["Categories"], "summary": "List categories", "description": "Retrieve a list of all categories and their ancestry. The returned list\nis not paginated.\n", "parameters": [ { "name": "filter[parent]", "in": "query", "schema": { "type": "string" }, "required": false, "example": "good-life", "description": "The unique identifier of a parent category for which to\nreturn only its children. Providing an invalid category\nidentifier results in a `404` response.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCategoriesResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:OTFUmA1YX3oq9Mtp" }, "pathParameters": {}, "queryParameters": { "filter[parent]": "good-life" }, "payload": null }, "response": { "data": [ { "type": "categories", "id": "hobbies", "attributes": { "name": "Hobbies" }, "relationships": { "parent": { "data": { "type": "categories", "id": "good-life" }, "links": { "related": "https://api.up.com.au/api/v1/categories/good-life" } }, "children": { "data": [], "links": { "related": "https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=hobbies" } } }, "links": { "self": "https://api.up.com.au/api/v1/categories/hobbies" } }, { "type": "categories", "id": "restaurants-and-cafes", "attributes": { "name": "Restaurants & Cafes" }, "relationships": { "parent": { "data": { "type": "categories", "id": "good-life" }, "links": { "related": "https://api.up.com.au/api/v1/categories/good-life" } }, "children": { "data": [], "links": { "related": "https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=restaurants-and-cafes" } } }, "links": { "self": "https://api.up.com.au/api/v1/categories/restaurants-and-cafes" } } ] } } } } } }, "/categories/{id}": { "get": { "tags": ["Categories"], "summary": "Retrieve category", "description": "Retrieve a specific category by providing its unique identifier.\n", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "restaurants-and-cafes", "description": "The unique identifier for the category.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCategoryResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:h3cqAp7XGqD2Jpg4" }, "pathParameters": { "id": "home" }, "queryParameters": {}, "payload": null }, "response": { "data": { "type": "categories", "id": "home", "attributes": { "name": "Home" }, "relationships": { "parent": { "data": null }, "children": { "data": [ { "type": "categories", "id": "groceries" } ], "links": { "related": "https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=home" } } }, "links": { "self": "https://api.up.com.au/api/v1/categories/home" } } } } } } } }, "/transactions/{transactionId}/relationships/category": { "patch": { "tags": ["Categories"], "summary": "Categorize transaction", "description": "Updates the category associated with a transaction. Only transactions\nfor which `isCategorizable` is set to true support this operation. The\n`id` is taken from the list exposed on `/categories` and cannot be one of\nthe top-level (parent) categories. To de-categorize a transaction, set\nthe entire `data` key to `null`. An HTTP `204` is returned on success.\nThe associated category, along with its request URL is also exposed via\nthe `category` relationship on the transaction resource returned from\n`/transactions/{id}`.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTransactionCategoryRequest" } } } }, "parameters": [ { "name": "transactionId", "in": "path", "schema": { "type": "string" }, "required": true, "example": "88b4ed70-7f15-4b46-a676-46aafad4c183", "description": "The unique identifier for the transaction.\n" } ], "responses": { "204": { "description": "Successful Response", "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:jxaEroUCArojsqOr", "Content-Type": "application/json" }, "pathParameters": { "transactionId": "b2372db2-f032-4350-b276-bfe25467087b" }, "queryParameters": {}, "payload": { "data": { "type": "categories", "id": "restaurants-and-cafes" } } }, "response": null } } } } }, "/util/ping": { "get": { "tags": ["Utility endpoints"], "summary": "Ping", "description": "Make a basic ping request to the API. This is useful to verify that\nauthentication is functioning correctly. On authentication success an\nHTTP `200` status is returned. On failure an HTTP `401` error response\nis returned.\n", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:qrwv9tQgS76mnS9G" }, "pathParameters": {}, "queryParameters": {}, "payload": null }, "response": { "meta": { "id": "f8178615-7fd7-47a6-9a6e-cf62b3313848", "statusEmoji": "⚡️" } } } }, "401": { "description": "Not Authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": {}, "pathParameters": {}, "queryParameters": {}, "payload": null }, "response": { "errors": [ { "status": "401", "title": "Not Authorized", "detail": "The request was not authenticated because no valid credential was found in the Authorization header, or the Authorization header was not present." } ] } } } } } }, "/tags": { "get": { "tags": ["Tags"], "summary": "List tags", "description": "Retrieve a list of all tags currently in use. The returned list is\n[paginated](#pagination) and can be scrolled by following the `next`\nand `prev` links where present. Results are ordered lexicographically.\nThe `transactions` relationship for each tag exposes a link\nto get the transactions with the given tag.\n", "parameters": [ { "name": "page[size]", "in": "query", "schema": { "type": "integer" }, "required": false, "example": 50, "description": "The number of records to return in each page.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTagsResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:bXd8NjT6vO5gfMvG" }, "pathParameters": {}, "queryParameters": { "page[size]": 2 }, "payload": null }, "response": { "data": [ { "type": "tags", "id": "Holiday", "relationships": { "transactions": { "links": { "related": "https://api.up.com.au/api/v1/transactions?filter%5Btag%5D=Holiday" } } } }, { "type": "tags", "id": "Pizza Night", "relationships": { "transactions": { "links": { "related": "https://api.up.com.au/api/v1/transactions?filter%5Btag%5D=Pizza+Night" } } } } ], "links": { "prev": null, "next": "https://api.up.com.au/api/v1/tags?page%5Bafter%5D=WyJQaXp6YSBOaWdodCJd&page%5Bsize%5D=2" } } } } } } }, "/transactions/{transactionId}/relationships/tags": { "post": { "tags": ["Tags"], "summary": "Add tags to transaction", "description": "Associates one or more tags with a specific transaction. No more than 6\ntags may be present on any single transaction. Duplicate tags are\nsilently ignored. An HTTP `204` is returned on success. The associated\ntags, along with this request URL, are also exposed via the `tags`\nrelationship on the transaction resource returned from\n`/transactions/{id}`.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTransactionTagsRequest" } } } }, "parameters": [ { "name": "transactionId", "in": "path", "schema": { "type": "string" }, "required": true, "example": "6259eac2-feac-417d-893e-84876c575913", "description": "The unique identifier for the transaction.\n" } ], "responses": { "204": { "description": "Successful Response", "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:UvlljHmCb9A9P78m", "Content-Type": "application/json" }, "pathParameters": { "transactionId": "667fd9d3-05d7-4eb4-b496-a406ca7da08d" }, "queryParameters": {}, "payload": { "data": [ { "type": "tags", "id": "Holiday" }, { "type": "tags", "id": "Queensland" } ] } }, "response": null } } } }, "delete": { "tags": ["Tags"], "summary": "Remove tags from transaction", "description": "Disassociates one or more tags from a specific transaction. Tags that are\nnot associated are silently ignored. An HTTP `204` is returned on\nsuccess. The associated tags, along with this request URL, are also\nexposed via the `tags` relationship on the transaction resource returned\nfrom `/transactions/{id}`.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTransactionTagsRequest" } } } }, "parameters": [ { "name": "transactionId", "in": "path", "schema": { "type": "string" }, "required": true, "example": "86aacb90-a718-43f2-bb06-c1e32542ab26", "description": "The unique identifier for the transaction.\n" } ], "responses": { "204": { "description": "Successful Response", "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:RFntp7VQQkErMliU", "Content-Type": "application/json" }, "pathParameters": { "transactionId": "8f3bd8ef-8d89-4e86-8d10-aa3e61c4afd6" }, "queryParameters": {}, "payload": { "data": [ { "type": "tags", "id": "Holiday" }, { "type": "tags", "id": "Queensland" } ] } }, "response": null } } } } }, "/transactions": { "get": { "tags": ["Transactions"], "summary": "List transactions", "description": "Retrieve a list of all transactions across all accounts for the currently\nauthenticated user. The returned list is [paginated](#pagination) and can\nbe scrolled by following the `next` and `prev` links where present. To\nnarrow the results to a specific date range pass one or both of\n`filter[since]` and `filter[until]` in the query string. These filter\nparameters **should not** be used for pagination. Results are ordered\nnewest first to oldest last.\n", "parameters": [ { "name": "page[size]", "in": "query", "schema": { "type": "integer" }, "required": false, "example": 30, "description": "The number of records to return in each page.\n" }, { "name": "filter[status]", "in": "query", "schema": { "$ref": "#/components/schemas/TransactionStatusEnum" }, "required": false, "example": "HELD", "description": "The transaction status for which to return records. This\ncan be used to filter `HELD` transactions from those\nthat are `SETTLED`.\n" }, { "name": "filter[since]", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "example": "2020-01-01T01:02:03+10:00", "description": "The start date-time from which to return records,\nformatted according to rfc-3339. Not to be used for\npagination purposes.\n" }, { "name": "filter[until]", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "example": "2020-02-01T01:02:03+10:00", "description": "The end date-time up to which to return records,\nformatted according to rfc-3339. Not to be used for\npagination purposes.\n" }, { "name": "filter[category]", "in": "query", "schema": { "type": "string" }, "required": false, "example": "good-life", "description": "The category identifier for which to filter transactions.\nBoth parent and child categories can be filtered through\nthis parameter. Providing an invalid category identifier\nresults in a `404` response.\n" }, { "name": "filter[tag]", "in": "query", "schema": { "type": "string" }, "required": false, "example": "Holiday", "description": "A transaction tag to filter for which to return records.\nIf the tag does not exist, zero records are returned and\na success response is given.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTransactionsResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:x2IN1pBWVKpwYQ1C" }, "pathParameters": {}, "queryParameters": { "page[size]": 1, "filter[tag]": "Pizza Night", "filter[status]": "SETTLED" }, "payload": null }, "response": { "data": [ { "type": "transactions", "id": "e38f484c-276e-4e87-9031-224564067d83", "attributes": { "status": "SETTLED", "rawText": null, "description": "David Taylor", "message": "Money for the pizzas last night.", "isCategorizable": true, "holdInfo": null, "roundUp": null, "cashback": null, "amount": { "currencyCode": "AUD", "value": "-59.98", "valueInBaseUnits": -5998 }, "foreignAmount": null, "cardPurchaseMethod": null, "settledAt": "2024-08-05T05:16:50+10:00", "createdAt": "2024-08-05T05:16:50+10:00", "transactionType": null, "note": null, "performingCustomer": { "displayName": "Bobby" } }, "relationships": { "account": { "data": { "type": "accounts", "id": "b47aa85f-0b67-46b2-a8d4-902f8e8b9d97" }, "links": { "related": "https://api.up.com.au/api/v1/accounts/b47aa85f-0b67-46b2-a8d4-902f8e8b9d97" } }, "transferAccount": { "data": null }, "category": { "data": null, "links": { "self": "https://api.up.com.au/api/v1/transactions/e38f484c-276e-4e87-9031-224564067d83/relationships/category" } }, "parentCategory": { "data": null }, "tags": { "data": [ { "type": "tags", "id": "Pizza Night" } ], "links": { "self": "https://api.up.com.au/api/v1/transactions/e38f484c-276e-4e87-9031-224564067d83/relationships/tags" } }, "attachment": { "data": null } }, "links": { "self": "https://api.up.com.au/api/v1/transactions/e38f484c-276e-4e87-9031-224564067d83" } } ], "links": { "prev": null, "next": null } } } } } } }, "/transactions/{id}": { "get": { "tags": ["Transactions"], "summary": "Retrieve transaction", "description": "Retrieve a specific transaction by providing its unique identifier.\n", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "57a749fd-4fc9-40da-a8d9-ec9cf1d8c9ff", "description": "The unique identifier for the transaction.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTransactionResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:zaoUoVWJiy1FHOQ5" }, "pathParameters": { "id": "20f1a541-356b-4363-aeba-18e21661b8e5" }, "queryParameters": {}, "payload": null }, "response": { "data": { "type": "transactions", "id": "20f1a541-356b-4363-aeba-18e21661b8e5", "attributes": { "status": "SETTLED", "rawText": "WARUNG BEBEK, UBUD INDONES", "description": "Warung Bebek Bengil", "message": null, "isCategorizable": true, "holdInfo": { "amount": { "currencyCode": "AUD", "value": "-107.92", "valueInBaseUnits": -10792 }, "foreignAmount": null }, "roundUp": { "amount": { "currencyCode": "AUD", "value": "-0.08", "valueInBaseUnits": -8 }, "boostPortion": null }, "cashback": null, "amount": { "currencyCode": "AUD", "value": "-107.92", "valueInBaseUnits": -10792 }, "foreignAmount": { "currencyCode": "IDR", "value": "-1053698.77", "valueInBaseUnits": -105369877 }, "cardPurchaseMethod": { "method": "CARD_ON_FILE", "cardNumberSuffix": "0001" }, "settledAt": "2024-08-03T04:00:00+10:00", "createdAt": "2024-08-03T04:00:00+10:00", "transactionType": null, "note": null, "performingCustomer": { "displayName": "Bobby" } }, "relationships": { "account": { "data": { "type": "accounts", "id": "20388753-0ba8-46ab-92f8-d186a9b3e2a8" }, "links": { "related": "https://api.up.com.au/api/v1/accounts/20388753-0ba8-46ab-92f8-d186a9b3e2a8" } }, "transferAccount": { "data": null }, "category": { "data": null, "links": { "self": "https://api.up.com.au/api/v1/transactions/20f1a541-356b-4363-aeba-18e21661b8e5/relationships/category" } }, "parentCategory": { "data": null }, "tags": { "data": [], "links": { "self": "https://api.up.com.au/api/v1/transactions/20f1a541-356b-4363-aeba-18e21661b8e5/relationships/tags" } }, "attachment": { "data": null } }, "links": { "self": "https://api.up.com.au/api/v1/transactions/20f1a541-356b-4363-aeba-18e21661b8e5" } } } } } } } }, "/accounts/{accountId}/transactions": { "get": { "tags": ["Transactions"], "summary": "List transactions by account", "description": "Retrieve a list of all transactions for a specific account. The returned\nlist is [paginated](#pagination) and can be scrolled by following the\n`next` and `prev` links where present. To narrow the results to a\nspecific date range pass one or both of `filter[since]` and\n`filter[until]` in the query string. These filter parameters\n**should not** be used for pagination. Results are ordered newest first\nto oldest last.\n", "parameters": [ { "name": "accountId", "in": "path", "schema": { "type": "string" }, "required": true, "example": "689a08de-fa65-4f2d-8b58-e49b17117dc7", "description": "The unique identifier for the account.\n" }, { "name": "page[size]", "in": "query", "schema": { "type": "integer" }, "required": false, "example": 30, "description": "The number of records to return in each page.\n" }, { "name": "filter[status]", "in": "query", "schema": { "$ref": "#/components/schemas/TransactionStatusEnum" }, "required": false, "example": "HELD", "description": "The transaction status for which to return records. This\ncan be used to filter `HELD` transactions from those\nthat are `SETTLED`.\n" }, { "name": "filter[since]", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "example": "2020-01-01T01:02:03+10:00", "description": "The start date-time from which to return records,\nformatted according to rfc-3339. Not to be used for\npagination purposes.\n" }, { "name": "filter[until]", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "example": "2020-02-01T01:02:03+10:00", "description": "The end date-time up to which to return records,\nformatted according to rfc-3339. Not to be used for\npagination purposes.\n" }, { "name": "filter[category]", "in": "query", "schema": { "type": "string" }, "required": false, "example": "good-life", "description": "The category identifier for which to filter transactions.\nBoth parent and child categories can be filtered through\nthis parameter. Providing an invalid category identifier\nresults in a `404` response.\n" }, { "name": "filter[tag]", "in": "query", "schema": { "type": "string" }, "required": false, "example": "Holiday", "description": "A transaction tag to filter for which to return records.\nIf the tag does not exist, zero records are returned and\na success response is given.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTransactionsResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:k6Zc7WP5K3WuBcLc" }, "pathParameters": { "accountId": "bccfbe8a-8d06-415d-b6fb-9f4e4507a3c2" }, "queryParameters": { "page[size]": 1, "filter[status]": "HELD", "filter[category]": "good-life" }, "payload": null }, "response": { "data": [ { "type": "transactions", "id": "08e78dd1-539c-40cc-a124-2af02e078d20", "attributes": { "status": "HELD", "rawText": "Spotify 0123456789", "description": "Spotify", "message": null, "isCategorizable": true, "holdInfo": { "amount": { "currencyCode": "AUD", "value": "-11.95", "valueInBaseUnits": -1195 }, "foreignAmount": null }, "roundUp": null, "cashback": null, "amount": { "currencyCode": "AUD", "value": "-11.95", "valueInBaseUnits": -1195 }, "foreignAmount": null, "cardPurchaseMethod": null, "settledAt": null, "createdAt": "2024-08-03T08:09:59+10:00", "transactionType": null, "note": null, "performingCustomer": { "displayName": "Bobby" } }, "relationships": { "account": { "data": { "type": "accounts", "id": "bccfbe8a-8d06-415d-b6fb-9f4e4507a3c2" }, "links": { "related": "https://api.up.com.au/api/v1/accounts/bccfbe8a-8d06-415d-b6fb-9f4e4507a3c2" } }, "transferAccount": { "data": null }, "category": { "data": { "type": "categories", "id": "tv-and-music" }, "links": { "self": "https://api.up.com.au/api/v1/transactions/08e78dd1-539c-40cc-a124-2af02e078d20/relationships/category", "related": "https://api.up.com.au/api/v1/categories/tv-and-music" } }, "parentCategory": { "data": { "type": "categories", "id": "good-life" }, "links": { "related": "https://api.up.com.au/api/v1/categories/good-life" } }, "tags": { "data": [], "links": { "self": "https://api.up.com.au/api/v1/transactions/08e78dd1-539c-40cc-a124-2af02e078d20/relationships/tags" } }, "attachment": { "data": null } }, "links": { "self": "https://api.up.com.au/api/v1/transactions/08e78dd1-539c-40cc-a124-2af02e078d20" } } ], "links": { "prev": null, "next": null } } } } } } }, "/webhooks": { "get": { "tags": ["Webhooks"], "summary": "List webhooks", "description": "Retrieve a list of configured webhooks. The returned list is\n[paginated](#pagination) and can be scrolled by following the `next`\nand `prev` links where present. Results are ordered oldest first to\nnewest last.\n", "parameters": [ { "name": "page[size]", "in": "query", "schema": { "type": "integer" }, "required": false, "example": 30, "description": "The number of records to return in each page.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:sGbPklakZzGRpyN8" }, "pathParameters": {}, "queryParameters": { "page[size]": 1 }, "payload": null }, "response": { "data": [ { "type": "webhooks", "id": "906ffa4f-9ce2-4e24-838b-c0f2ac1941d9", "attributes": { "url": "http://example.com/webhook-1", "description": "Webhook number 1", "createdAt": "2024-08-04T12:19:01+10:00" }, "relationships": { "logs": { "links": { "related": "https://api.up.com.au/api/v1/webhooks/906ffa4f-9ce2-4e24-838b-c0f2ac1941d9/logs" } } }, "links": { "self": "https://api.up.com.au/api/v1/webhooks/906ffa4f-9ce2-4e24-838b-c0f2ac1941d9" } } ], "links": { "prev": null, "next": "https://api.up.com.au/api/v1/webhooks?page%5Bafter%5D=WyIyMDI0LTA4LTA0VDAyOjE5OjAxLjE3MDA3ODAwMFoiLCI5MDZmZmE0Zi05Y2UyLTRlMjQtODM4Yi1jMGYyYWMxOTQxZDkiXQ%3D%3D&page%5Bsize%5D=1" } } } } } }, "post": { "tags": ["Webhooks"], "summary": "Create webhook", "description": "Create a new webhook with a given URL. The URL will receive webhook\nevents as JSON-encoded `POST` requests. The URL must respond with a HTTP\n`200` status on success.\n\nThere is currently a limit of 10 webhooks at any given time. Once this\nlimit is reached, existing webhooks will need to be deleted before new\nwebhooks can be created.\n\nEvent delivery is retried with exponential backoff if the URL is\nunreachable or it does not respond with a `200` status. The response\nincludes a `secretKey` attribute, which is used to sign requests sent to\nthe webhook URL. It will not be returned from any other endpoints within\nthe Up API. If the `secretKey` is lost, simply create a new webhook with\nthe same URL, capture its `secretKey` and then delete the original\nwebhook. See [Handling webhook events](#callback_post_webhookURL) for\ndetails on how to process webhook events.\n\nIt is probably a good idea to test the webhook by\n[sending it a `PING` event](#post_webhooks_webhookId_ping) after creating\nit.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:Ai3k0uTDg9UbsMSn", "Content-Type": "application/json" }, "pathParameters": {}, "queryParameters": {}, "payload": { "data": { "attributes": { "url": "http://example.com/webhook", "description": "Example webhook" } } } }, "response": { "data": { "type": "webhooks", "id": "e1dc11ce-c175-4c43-a969-6f8ffc8adc5b", "attributes": { "url": "http://example.com/webhook", "description": "Example webhook", "secretKey": "EIY19vc8Z7n4Ub58Ex13RxKfsnLyZ6pwwT6wyuv4WboOgvA3xW33BZpkxLDb5hfQ", "createdAt": "2024-08-06T12:19:01+10:00" }, "relationships": { "logs": { "links": { "related": "https://api.up.com.au/api/v1/webhooks/e1dc11ce-c175-4c43-a969-6f8ffc8adc5b/logs" } } }, "links": { "self": "https://api.up.com.au/api/v1/webhooks/e1dc11ce-c175-4c43-a969-6f8ffc8adc5b" } } } } } }, "callbacks": { "Event": { "{webhookURL}": { "post": { "summary": "Handling webhook events", "description": "Once you have created a webhook in the Up API, events are sent to the\nwebhook’s configured URL as JSON-encoded `POST` requests. The webhook\nURL must respond with a HTTP `200` status on success.\n\nIt is important that the URL responds in a timely manner. If the URL\ntakes too long to respond (currently 30s), the request will be timed\nout. For this reason it is strongly advised to avoid any heavy\nprocessing before a response has been returned from the URL. A common\nsolution to this problem is to use a message broker such as RabbitMQ\nto do the work asynchronously.\n\nEvent delivery is retried with exponential backoff in the case of any\nnon-`200` response status, if the URL is unreachable, or if the request\nis timed out.\n\nRefer to the `eventType` attribute in order to determine what course of\naction to take when handling the event. The following event types are\ncurrently sent:\n\n**`PING`**\n\nManually triggered by calls to the webhook `ping` endpoint. Used for\ntesting and debugging purposes.\n\n**`TRANSACTION_CREATED`**\n\nTriggered whenever a new transaction is created in Up. This event\nincludes a `transaction` relationship that provides the unique\nidentifier for the transaction and a link to the transaction within the\nUp API. This link should be used to retrieve the complete transaction\ndata.\n\n**`TRANSACTION_SETTLED`**\n\nTriggered whenever a transaction transitions from the `HELD` status to\nthe `SETTLED` status. This event includes a `transaction` relationship\nthat provides the unique identifier for the transaction and a link to\nthe transaction within the Up API. This link should be used to retrieve\nthe complete transaction data.\n\nDue to external factors in banking processes, on rare occasions this\nevent may not be triggered. Separate `TRANSACTION_DELETED` and\n`TRANSACTION_CREATED` events will be received in its place.\n\n**`TRANSACTION_DELETED`**\n\nTriggered whenever a `HELD` transaction is deleted from Up. This\ngenerally occurs for example when a hotel deposit is returned. This\nevent includes a `transaction` relationship that provides the unique\nidentifier for the transaction, however no link is provided to the\ntransaction within the Up API as it no longer exists.\n\n## Securing Webhook Event Handlers\n\nIncoming webhook event requests include a `X-Up-Authenticity-Signature`\nheader, which can be used to verify that the event was sent by Up.\nVerification of the signature requires knowledge of the shared\n`secretKey` that was returned upon creation of the webhook. This key is\nknown only to your application and to Up.\n\nThe verification process involves:\n\n1. Taking the raw, unparsed webhook event request body.\n2. Computing the SHA-256 HMAC signature of the request body, using the\n shared `secretKey`.\n3. Comparing the computed HMAC signature with the value of the\n `X-Up-Authenticity-Signature` header.\n\nIf the computed SHA-256 HMAC signature matches the\n`X-Up-Authenticity-Signature` header, the request is valid.\n\nA few language-specific examples follow.\n\n**Ruby**:\n\nThis example uses the Ruby on Rails framework.\n\n```ruby\nrequire 'openssl'\n\ndef handle_webhook_event\n received_signature =\n request.headers['X-Up-Authenticity-Signature']\n\n signature = OpenSSL::HMAC.hexdigest(\n 'SHA256',\n secret_key,\n request.raw_post,\n )\n\n if Rack::Utils.secure_compare(received_signature, signature)\n # Process webhook event\n end\nend\n```\n\n**PHP**:\n\nThis example uses the Laravel framework.\n\n```php\npublic function handleWebhookEvent(Request $request) {\n $received_signature = $request->header(\n 'X-Up-Authenticity-Signature',\n ''\n );\n $raw_body = $request->getContent();\n $signature = hash_hmac('sha256', $raw_body, $this->secretKey);\n\n if (hash_equals($signature, $received_signature)) {\n // Process webhook event\n }\n}\n```\n\n**Go**:\n\nThis example is in plain Go.\n\n```go\nimport (\n \"crypto/hmac\"\n \"crypto/sha256\"\n \"encoding/hex\"\n \"io\"\n \"net/http\"\n)\n\nfunc handleWebhookEvent(w http.ResponseWriter, r *http.Request) {\n receivedSignature, _ := hex.DecodeString(\n r.Header.Get(\"X-Up-Authenticity-Signature\"),\n )\n\n mac := hmac.New(sha256.New, secretKey)\n io.Copy(mac, r.Body)\n signature := mac.Sum(nil)\n\n if hmac.Equal(signature, receivedSignature)\n // Process webhook event\n }\n}\n```\n\nIf the `secretKey` for a webhook is lost, simply create a new webhook\nwith the same URL, capture the returned `secretKey` and delete the\noriginal webhook.\n", "parameters": [ { "name": "X-Up-Authenticity-Signature", "in": "header", "schema": { "type": "string" }, "required": false, "example": "317c0a8ea81df3f53c1d2aef5dcbf60492d0df557197b2990e71daa4a0693364", "description": "The SHA-256 HMAC signature of the raw request body, signed using\nthe `secretKey` of the webhook.\n" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventCallback" } } } }, "responses": { "200": { "description": "Successful Response" } }, "x-up:example": { "type": "examplePayload", "payload": { "data": { "type": "webhook-events", "id": "32e730bd-752d-4ae8-a8e2-bab115c72b6d", "attributes": { "eventType": "TRANSACTION_CREATED", "createdAt": "2024-08-06T12:19:02+10:00" }, "relationships": { "webhook": { "data": { "type": "webhooks", "id": "135017b5-2585-4564-ac7d-040043d51667" }, "links": { "related": "https://api.up.com.au/api/v1/webhooks/135017b5-2585-4564-ac7d-040043d51667" } }, "transaction": { "data": { "type": "transactions", "id": "516f5342-2d25-47b1-a46c-40466ddae069" }, "links": { "related": "https://api.up.com.au/api/v1/transactions/516f5342-2d25-47b1-a46c-40466ddae069" } } } } } } } } } } } }, "/webhooks/{id}": { "get": { "tags": ["Webhooks"], "summary": "Retrieve webhook", "description": "Retrieve a specific webhook by providing its unique identifier.\n", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "48984142-bb60-4fd9-8db2-ed72cfc2a0ba", "description": "The unique identifier for the webhook.\n" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebhookResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:Jdn3RtGUFDxYfTkp" }, "pathParameters": { "id": "362f41e4-c750-40ed-8bec-73ecca1e65e1" }, "queryParameters": {}, "payload": null }, "response": { "data": { "type": "webhooks", "id": "362f41e4-c750-40ed-8bec-73ecca1e65e1", "attributes": { "url": "http://example.com/webhook-2", "description": "Webhook number 2", "createdAt": "2024-08-05T12:19:03+10:00" }, "relationships": { "logs": { "links": { "related": "https://api.up.com.au/api/v1/webhooks/362f41e4-c750-40ed-8bec-73ecca1e65e1/logs" } } }, "links": { "self": "https://api.up.com.au/api/v1/webhooks/362f41e4-c750-40ed-8bec-73ecca1e65e1" } } } } } } }, "delete": { "tags": ["Webhooks"], "summary": "Delete webhook", "description": "Delete a specific webhook by providing its unique identifier. Once\ndeleted, webhook events will no longer be sent to the configured URL.\n", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "be530308-60e2-489b-9c73-ab0db6fd132d", "description": "The unique identifier for the webhook.\n" } ], "responses": { "204": { "description": "Deleted", "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:AICm0MfozWEhnfci" }, "pathParameters": { "id": "daf513b4-7c2c-441b-a77c-3b2b63f260f9" }, "queryParameters": {}, "payload": null }, "response": null } } } } }, "/webhooks/{webhookId}/ping": { "post": { "tags": ["Webhooks"], "summary": "Ping webhook", "description": "Send a `PING` event to a webhook by providing its unique identifier.\nThis is useful for testing and debugging purposes. The event is delivered\nasynchronously and its data is returned in the response to this request.\n", "parameters": [ { "name": "webhookId", "in": "path", "schema": { "type": "string" }, "required": true, "example": "ca59a175-79fa-4467-867f-b0cf582ee6bd", "description": "The unique identifier for the webhook.\n" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventCallback" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:3aQCtgODipPleMHV", "Content-Type": "application/json" }, "pathParameters": { "webhookId": "2649c1f0-b03b-4c21-bb85-331d53644305" }, "queryParameters": {}, "payload": "" }, "response": { "data": { "type": "webhook-events", "id": "973606bb-ad40-426d-9bd8-d76ab70cd038", "attributes": { "eventType": "PING", "createdAt": "2024-08-06T12:19:06+10:00" }, "relationships": { "webhook": { "data": { "type": "webhooks", "id": "2649c1f0-b03b-4c21-bb85-331d53644305" }, "links": { "related": "https://api.up.com.au/api/v1/webhooks/2649c1f0-b03b-4c21-bb85-331d53644305" } } } } } } } } } }, "/webhooks/{webhookId}/logs": { "get": { "tags": ["Webhooks"], "summary": "List webhook logs", "description": "Retrieve a list of delivery logs for a webhook by providing its unique\nidentifier. This is useful for analysis and debugging purposes. The\nreturned list is [paginated](#pagination) and can be scrolled by\nfollowing the `next` and `prev` links where present. Results are ordered\nnewest first to oldest last. Logs may be automatically purged after a\nperiod of time.\n", "parameters": [ { "name": "webhookId", "in": "path", "schema": { "type": "string" }, "required": true, "example": "e579c0fe-62e7-47de-b436-4b1dfe110b35", "description": "The unique identifier for the webhook.\n" }, { "name": "page[size]", "in": "query", "schema": { "type": "integer" }, "required": false, "example": 30, "description": "The number of records to return in each page.\n" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookDeliveryLogsResponse" } } }, "x-up:example": { "type": "exampleRequestResponse", "request": { "headers": { "Authorization": "Bearer up:demo:jzQH9GsHMtCmwyr8" }, "pathParameters": { "webhookId": "cce901e8-e10b-4d4d-a615-f1902e4736d4" }, "queryParameters": { "page[size]": 1 }, "payload": null }, "response": { "data": [ { "type": "webhook-delivery-logs", "id": "03743de3-1dc8-4893-b1b0-86ab5d613c5b", "attributes": { "request": { "body": "{\"data\":{\"type\":\"webhook-events\",\"id\":\"011308c1-861c-4d04-ba85-f867eadf202d\",\"attributes\":{\"eventType\":\"TRANSACTION_CREATED\",\"createdAt\":\"2024-08-05T12:20:07+10:00\"},\"relationships\":{\"webhook\":{\"data\":{\"type\":\"webhooks\",\"id\":\"cce901e8-e10b-4d4d-a615-f1902e4736d4\"},\"links\":{\"related\":\"https://api.up.com.au/api/v1/webhooks/cce901e8-e10b-4d4d-a615-f1902e4736d4\"}},\"transaction\":{\"data\":{\"type\":\"transactions\",\"id\":\"169c1684-45c7-41c1-95fa-97082b319e6c\"},\"links\":{\"related\":\"https://api.up.com.au/api/v1/transactions/169c1684-45c7-41c1-95fa-97082b319e6c\"}}}}}" }, "response": { "statusCode": 200, "body": "{\"ok\":true}" }, "deliveryStatus": "DELIVERED", "createdAt": "2024-08-05T12:20:07+10:00" }, "relationships": { "webhookEvent": { "data": { "type": "webhook-events", "id": "011308c1-861c-4d04-ba85-f867eadf202d" } } } } ], "links": { "prev": null, "next": "https://api.up.com.au/api/v1/webhooks/cce901e8-e10b-4d4d-a615-f1902e4736d4/logs?page%5Bafter%5D=WyIyMDI0LTA4LTA1VDAyOjIwOjA3Ljk2MjMzODAwMFoiLCIwMzc0M2RlMy0xZGM4LTQ4OTMtYjFiMC04NmFiNWQ2MTNjNWIiXQ%3D%3D&page%5Bsize%5D=1" } } } } } } } } }