# Currency exchange ## Retrieving all exchange rates > Retrieves all exchange rates. You can filter and sort the results by the fields, for example \`source\` or \`target currency\`. ```json {"openapi":"3.0.0","info":{"title":"Currency Service","version":"0.0.1"},"tags":[{"name":"Currency exchange"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["currency.currency_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"currency.currency_manage":"The scope allows you to create, update, and delete currencies and currency exchanges","currency.currency_read":"The scope allows you to retrieve currencies and currency exchanges."}}}}},"parameters":{"trait_tenant":{"name":"tenant","in":"path","required":true,"description":"The tenant that the caller is acting upon.\n\n**Note:** This value must always be provided in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}},"trait_paged_pageNumber":{"name":"pageNumber","in":"query","description":"The page number to be retrieved where the size of the pages is specified by the `pageSize` parameter.\nThe number of the first page is 1.\n","schema":{"default":1,"minimum":1,"type":"integer"}},"trait_paged_pageSize":{"name":"pageSize","in":"query","description":"The number of documents being retrieved on one page.\n","schema":{"default":60,"minimum":1,"type":"integer"}},"trait_XTotalCount_header":{"in":"header","name":"X-Total-Count","required":false,"description":"The flag indicates if the total count of items should be returned. The total count will be returned as a value of the `X-Total-Count` header.","schema":{"default":false,"type":"boolean"}},"trait_sort":{"in":"query","name":"sort","required":false,"description":"Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in the following format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.","schema":{"type":"string"}},"trait_exchange_source_currency":{"name":"sourceCurrency","in":"query","required":false,"schema":{"type":"string"},"description":"Returns all exchange definitions for which the source currency matches the pattern. The `contains` operation is used for the parameter. "},"trait_exchange_target_currency":{"name":"targetCurrency","in":"query","required":false,"schema":{"type":"string"},"description":"Returns all exchange definitions for which the target currency matches the pattern. The `contains` operation is used for the parameter. "}},"schemas":{"exchangeRateRetrieval":{"title":"exchangeRateRetrieval","type":"object","properties":{"code":{"type":"string","description":"Identifier of the exchange rate. The identifier consists of the source currency and the target currency separated by an underscore."},"sourceCurrency":{"type":"string","description":"Source currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system."},"targetCurrency":{"type":"string","description":"Target currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system."},"rate":{"type":"string","description":"Represents the exchange rate.\n\nThe value of the field is represented by a number where the cent part is separated by a dot. For example `1.09`. The cent part is not limited just to two digits. A rate with any precision can be returned. For example: `1.091934212`"},"metadata":{"$ref":"#/components/schemas/metadata"}}},"metadata":{"type":"object","properties":{"createdAt":{"description":"Time of document creation.","type":"string","format":"date-time"},"modifiedAt":{"description":"Time of document modification.","type":"string","format":"date-time"},"version":{"minimum":1,"type":"integer","description":"Document version."}}},"errorMessage":{"title":"error","description":"Schema for API-specific errors.","type":"object","properties":{"currencyCode":{"type":"string"},"code":{"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"classification of the error type, lower case with underscore eg validation_failure","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"list of problems causing this error","type":"array","items":{"title":"errorDetail","description":"schema for specific error cause","type":"string"}},"errorCode":{"type":"string"}},"required":["status","code"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/currency/{tenant}/exchanges":{"get":{"summary":"Retrieving all exchange rates","description":"Retrieves all exchange rates. You can filter and sort the results by the fields, for example `source` or `target currency`.","parameters":[{"$ref":"#/components/parameters/trait_tenant"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_XTotalCount_header"},{"$ref":"#/components/parameters/trait_sort"},{"$ref":"#/components/parameters/trait_exchange_source_currency"},{"$ref":"#/components/parameters/trait_exchange_target_currency"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/exchangeRateRetrieval"}}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"tags":["Currency exchange"],"operationId":"GET-currency-retrieve-exchange-rates"}}}} ``` ## Creating a new exchange rate > Creates a new exchange rate between two currencies. \ > \ > \*\*Note:\*\* Both the source and target currency codes must be compliant with the ISO-4217 standard () and must be defined in the system. ```json {"openapi":"3.0.0","info":{"title":"Currency Service","version":"0.0.1"},"tags":[{"name":"Currency exchange"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["currency.currency_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"currency.currency_manage":"The scope allows you to create, update, and delete currencies and currency exchanges","currency.currency_read":"The scope allows you to retrieve currencies and currency exchanges."}}}}},"parameters":{"trait_tenant":{"name":"tenant","in":"path","required":true,"description":"The tenant that the caller is acting upon.\n\n**Note:** This value must always be provided in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}}},"schemas":{"exchangeRateCreationRequest":{"title":"exchangeRate","type":"object","properties":{"sourceCurrency":{"type":"string","description":"The source currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system."},"targetCurrency":{"type":"string","description":"The target currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system."},"rate":{"type":"string","description":"Represents the exchange rate.\n\nThe value of the field is represented by a number where the cent part is separated by a comma. For example `1.09`. The cent part is not limited just to two digits. A rate with any precision can be returned. For example: `1.091934212`"}},"required":["sourceCurrency","targetCurrency","rate"]},"exchangeRateResponse":{"title":"exchangeRateResponse","type":"object","description":"Represents the response after a successful exchange rate creation.","properties":{"code":{"type":"string","description":"Code of the newly created exchange rate in the following format: `sourceCurrency_targetCurrency`.\n"}}},"errorMessage":{"title":"error","description":"Schema for API-specific errors.","type":"object","properties":{"currencyCode":{"type":"string"},"code":{"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"classification of the error type, lower case with underscore eg validation_failure","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"list of problems causing this error","type":"array","items":{"title":"errorDetail","description":"schema for specific error cause","type":"string"}},"errorCode":{"type":"string"}},"required":["status","code"]}},"responses":{"BadRequest_400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Conflict_409":{"description":"Conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/currency/{tenant}/exchanges":{"post":{"summary":"Creating a new exchange rate","description":"Creates a new exchange rate between two currencies. \n\n**Note:** Both the source and target currency codes must be compliant with the ISO-4217 standard (https://www.iso.org/iso-4217-currency-codes.html) and must be defined in the system. ","parameters":[{"$ref":"#/components/parameters/trait_tenant"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/exchangeRateCreationRequest"}}},"description":""},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/exchangeRateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"tags":["Currency exchange"],"operationId":"POST-currency-create-exchange-rate"}}}} ``` ## Retrieving an exchange rate by code > Retrieves a currency exchange rate definition by code. ```json {"openapi":"3.0.0","info":{"title":"Currency Service","version":"0.0.1"},"tags":[{"name":"Currency exchange"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["currency.currency_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"currency.currency_manage":"The scope allows you to create, update, and delete currencies and currency exchanges","currency.currency_read":"The scope allows you to retrieve currencies and currency exchanges."}}}}},"parameters":{"trait_tenant":{"name":"tenant","in":"path","required":true,"description":"The tenant that the caller is acting upon.\n\n**Note:** This value must always be provided in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}}},"schemas":{"exchangeRateRetrieval":{"title":"exchangeRateRetrieval","type":"object","properties":{"code":{"type":"string","description":"Identifier of the exchange rate. The identifier consists of the source currency and the target currency separated by an underscore."},"sourceCurrency":{"type":"string","description":"Source currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system."},"targetCurrency":{"type":"string","description":"Target currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system."},"rate":{"type":"string","description":"Represents the exchange rate.\n\nThe value of the field is represented by a number where the cent part is separated by a dot. For example `1.09`. The cent part is not limited just to two digits. A rate with any precision can be returned. For example: `1.091934212`"},"metadata":{"$ref":"#/components/schemas/metadata"}}},"metadata":{"type":"object","properties":{"createdAt":{"description":"Time of document creation.","type":"string","format":"date-time"},"modifiedAt":{"description":"Time of document modification.","type":"string","format":"date-time"},"version":{"minimum":1,"type":"integer","description":"Document version."}}},"errorMessage":{"title":"error","description":"Schema for API-specific errors.","type":"object","properties":{"currencyCode":{"type":"string"},"code":{"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"classification of the error type, lower case with underscore eg validation_failure","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"list of problems causing this error","type":"array","items":{"title":"errorDetail","description":"schema for specific error cause","type":"string"}},"errorCode":{"type":"string"}},"required":["status","code"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"Resource has not been found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/currency/{tenant}/exchanges/{code}":{"get":{"summary":"Retrieving an exchange rate by code","description":"Retrieves a currency exchange rate definition by code.","parameters":[{"$ref":"#/components/parameters/trait_tenant"}],"responses":{"200":{"description":"Exchange rate returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/exchangeRateRetrieval"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"tags":["Currency exchange"],"operationId":"GET-currency-retrieve-exchange-rate"}}}} ``` ## Updating an exchange rate by code > Updates an existing exchange rate by code. \ > \ > \*\*Note:\*\* The exchange rate code, source, and target currencies are immutable, so they cannot be changed in this request. Only the \`rate\` field can be changed. ```json {"openapi":"3.0.0","info":{"title":"Currency Service","version":"0.0.1"},"tags":[{"name":"Currency exchange"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["currency.currency_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"currency.currency_manage":"The scope allows you to create, update, and delete currencies and currency exchanges","currency.currency_read":"The scope allows you to retrieve currencies and currency exchanges."}}}}},"parameters":{"trait_tenant":{"name":"tenant","in":"path","required":true,"description":"The tenant that the caller is acting upon.\n\n**Note:** This value must always be provided in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}}},"schemas":{"exchangeRateUpdateRequest":{"title":"exchangeRateUpdateRequest","type":"object","properties":{"rate":{"type":"string","description":"Represents the exchange rate.\n\nThe value of the field is represented by a number where the cent part is separated by a comma. For example, `1.09`. The cent part is not limited just to two digits. A rate with any precision can be returned. For example: `1.09193421`"},"metadata":{"$ref":"#/components/schemas/updateMetadata"}},"required":["rate","metadata"]},"updateMetadata":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Current version of the updated document."}},"required":["version"]},"errorMessage":{"title":"error","description":"Schema for API-specific errors.","type":"object","properties":{"currencyCode":{"type":"string"},"code":{"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"classification of the error type, lower case with underscore eg validation_failure","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"list of problems causing this error","type":"array","items":{"title":"errorDetail","description":"schema for specific error cause","type":"string"}},"errorCode":{"type":"string"}},"required":["status","code"]}},"responses":{"BadRequest_400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"Resource has not been found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Conflict_409":{"description":"Conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/currency/{tenant}/exchanges/{code}":{"put":{"summary":"Updating an exchange rate by code","description":"Updates an existing exchange rate by code. \n\n**Note:** The exchange rate code, source, and target currencies are immutable, so they cannot be changed in this request. Only the `rate` field can be changed.","parameters":[{"$ref":"#/components/parameters/trait_tenant"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/exchangeRateUpdateRequest"}}}},"responses":{"204":{"description":"Exchange rate updated"},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"tags":["Currency exchange"],"operationId":"PUT-currency-update-exchange-rate"}}}} ``` ## Deleting an exchange rate > Deletes the exchange rate definition by the provided code. If given definition does not exist in the system, the http code \`204\` will be returned.
```json {"openapi":"3.0.0","info":{"title":"Currency Service","version":"0.0.1"},"tags":[{"name":"Currency exchange"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["currency.currency_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"currency.currency_manage":"The scope allows you to create, update, and delete currencies and currency exchanges","currency.currency_read":"The scope allows you to retrieve currencies and currency exchanges."}}}}},"parameters":{"trait_tenant":{"name":"tenant","in":"path","required":true,"description":"The tenant that the caller is acting upon.\n\n**Note:** This value must always be provided in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"errorMessage":{"title":"error","description":"Schema for API-specific errors.","type":"object","properties":{"currencyCode":{"type":"string"},"code":{"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"classification of the error type, lower case with underscore eg validation_failure","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"list of problems causing this error","type":"array","items":{"title":"errorDetail","description":"schema for specific error cause","type":"string"}},"errorCode":{"type":"string"}},"required":["status","code"]}}},"paths":{"/currency/{tenant}/exchanges/{code}":{"delete":{"summary":"Deleting an exchange rate","description":"Deletes the exchange rate definition by the provided code. If given definition does not exist in the system, the http code `204` will be returned.\n","parameters":[{"$ref":"#/components/parameters/trait_tenant"}],"responses":{"204":{"description":"Exchange rate deleted"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"tags":["Currency exchange"],"operationId":"DELETE-currency-remove-exchange-rate"}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.emporix.io/api-references-1/readme/api-reference-11/currency-exchange.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.