Finance APIs
Operation for authenticating, getting obligation and submitting vat return to HMRC test enviroment.
Use GovTestScenarioHeader to change test enviroment response, see HMRC developer page for valid test headers.
If authentication code is sent inn, then an authentication token will be fetched from HMRC api and stored. If authentication code is not sent, then stored token will be used. Token is used in all api calls to HMRC api's.
If VATPeriod is sent then obligation for VATPeriod will be fetched.
If PeriodKey is sent then vat return will be submitted, Form is required to submit return. This is an API operation. Read the documentation pages for more information about API operations.
| HTTP method | POST |
| URI | https://api.rambase.net/base/companies/current/operating-countries/{countryId}/vat-specification?vatPeriod={vatPeriodId}/api-operations/100981/instances |
| Supported formats | Xml, Html, Json (ex. $format=json) |
| - URI parameter {countryId} |
Country identifier
Integer, minimum 10000 |
| Successful HTTP status code | 200 |
| API resource identifier | 4209, version 4 |
The following body must be added to the request. Mouse over fieldnames for description and other useful information about the fields. Note that fields in bold are required/mandatory.
VATPeriodKey
The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol.
This field is optional.
>{String}</VATPeriodKey>IsFinalised
Declaration that the user has finalised their VAT return.
Default value: False
This field is optional.
>{Boolean}</IsFinalised>Authentication
This field is optional.
>Code
Code to be exchanged for a OAUTH 2 access token.
This field is optional.
>{String}</Code>VATPeriod
Accounting period this VAT posting belongs to
Minimum value: 192001
Maximum value: 212012
This field is optional.
>{Integer}</VATPeriod>VATRegistrationNumber
Required/mandatory field
Unique number assigned by the relevant tax authority to identify a party for use in relation to value added tax (VAT)
>{String}</VATRegistrationNumber>Form
This field is optional.
>Box1
VAT due on sales and other outputs.
Minimum value: -9999999999999.99
Maximum value: 99999999999.99
This field is optional.
>{Decimal}</Box1>Box2
VAT due on acquisitions from other EC Member States.
Minimum value: -9999999999999.99
Maximum value: 99999999999.99
This field is optional.
>{Decimal}</Box2>Box3
Total VAT due (the sum of box1 and box2).
Minimum value: -9999999999999.99
Maximum value: 99999999999.99
This field is optional.
>{Decimal}</Box3>Box4
VAT reclaimed on purchases and other inputs (including acquisitions from the EC).
Minimum value: -9999999999999.99
Maximum value: 99999999999.99
This field is optional.
>{Decimal}</Box4>Box5
The difference between box3 and box4.
Minimum value: 0
Maximum value: 99999999999.99
This field is optional.
>{Decimal}</Box5>Box6
Total value of sales and all other outputs excluding any VAT.
Minimum value: -9999999999999
Maximum value: 99999999999
This field is optional.
>{Decimal}</Box6>Box7
Total value of purchases and all other inputs excluding any VAT (including exempt purchases).
Minimum value: -9999999999999
Maximum value: 99999999999
This field is optional.
>{Decimal}</Box7>Box8
Total value of all supplies of goods and related costs, excluding any VAT, to other EC member states.
Minimum value: -9999999999999
Maximum value: 99999999999
This field is optional.
>{Decimal}</Box8>Box9
Total value of acquisitions of goods and related costs excluding any VAT, from other EC member states.
Minimum value: -9999999999999
Maximum value: 99999999999
This field is optional.
>{Decimal}</Box9>DoNotTrackOption
Indicates if browser doNotTrackOption is on.
Default value: False
This field is optional.
>{Boolean}</DoNotTrackOption>UserAgent
Required/mandatory field
The browser useragent.
>{String}</UserAgent>Plugins
Required/mandatory field
list of plugins installed in browser.
>{String}</Plugins>DeviceUUID
Required/mandatory field
A unique identifier for the originating device.
>{String}</DeviceUUID>LocalIpAdresses
Required/mandatory field
The local ip adresses belonging to originating device.
>{String}</LocalIpAdresses>LocalIpAdressesTimeStamp
Required/mandatory field
UTC timestamp for when local ip adresses where gathered.
>{String}</LocalIpAdressesTimeStamp>Screen
Required/mandatory field
Information on originating devices screen resolution, pixel ratio and color depth.
>{String}</Screen>TimeZone
Required/mandatory field
timezone of originating device.
>{String}</TimeZone>LoginTime
Required/mandatory field
UTC timestamp for when user logged in.
>{String}</LoginTime>TwoFactorAuthenticationMethod
Required/mandatory field
Which two-factor method was used to authenticate.
>{String}</TwoFactorAuthenticationMethod>WindowSize
Required/mandatory field
The originating devices browser window size.
>{String}</WindowSize>TestData
This field is optional.
>GovTestScenarioHeader
sets the value for Gov-Test-Scenario header. the value 'default' signals to not set this header so as to recieve normal response from test enviroment.
Default value: default
This field is optional.
>{String}</GovTestScenarioHeader>VATPeriodKey
The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol.
This field is optional.
": "{String}",IsFinalised
Declaration that the user has finalised their VAT return.
Default value: False
This field is optional.
": "{Boolean}",Authentication
This field is optional.
": {Code
Code to be exchanged for a OAUTH 2 access token.
This field is optional.
": "{String}"VATPeriod
Accounting period this VAT posting belongs to
Minimum value: 192001
Maximum value: 212012
This field is optional.
": "{Integer}",VATRegistrationNumber
Required/mandatory field
Unique number assigned by the relevant tax authority to identify a party for use in relation to value added tax (VAT)
": "{String}"Form
This field is optional.
": {Box1
VAT due on sales and other outputs.
Minimum value: -9999999999999.99
Maximum value: 99999999999.99
This field is optional.
": "{Decimal}",Box2
VAT due on acquisitions from other EC Member States.
Minimum value: -9999999999999.99
Maximum value: 99999999999.99
This field is optional.
": "{Decimal}",Box3
Total VAT due (the sum of box1 and box2).
Minimum value: -9999999999999.99
Maximum value: 99999999999.99
This field is optional.
": "{Decimal}",Box4
VAT reclaimed on purchases and other inputs (including acquisitions from the EC).
Minimum value: -9999999999999.99
Maximum value: 99999999999.99
This field is optional.
": "{Decimal}",Box5
The difference between box3 and box4.
Minimum value: 0
Maximum value: 99999999999.99
This field is optional.
": "{Decimal}",Box6
Total value of sales and all other outputs excluding any VAT.
Minimum value: -9999999999999
Maximum value: 99999999999
This field is optional.
": "{Decimal}",Box7
Total value of purchases and all other inputs excluding any VAT (including exempt purchases).
Minimum value: -9999999999999
Maximum value: 99999999999
This field is optional.
": "{Decimal}",Box8
Total value of all supplies of goods and related costs, excluding any VAT, to other EC member states.
Minimum value: -9999999999999
Maximum value: 99999999999
This field is optional.
": "{Decimal}",Box9
Total value of acquisitions of goods and related costs excluding any VAT, from other EC member states.
Minimum value: -9999999999999
Maximum value: 99999999999
This field is optional.
": "{Decimal}"DoNotTrackOption
Indicates if browser doNotTrackOption is on.
Default value: False
This field is optional.
": "{Boolean}",UserAgent
Required/mandatory field
The browser useragent.
": "{String}",Plugins
Required/mandatory field
list of plugins installed in browser.
": "{String}",DeviceUUID
Required/mandatory field
A unique identifier for the originating device.
": "{String}",LocalIpAdresses
Required/mandatory field
The local ip adresses belonging to originating device.
": "{String}",LocalIpAdressesTimeStamp
Required/mandatory field
UTC timestamp for when local ip adresses where gathered.
": "{String}",Screen
Required/mandatory field
Information on originating devices screen resolution, pixel ratio and color depth.
": "{String}",TimeZone
Required/mandatory field
timezone of originating device.
": "{String}",LoginTime
Required/mandatory field
UTC timestamp for when user logged in.
": "{String}",TwoFactorAuthenticationMethod
Required/mandatory field
Which two-factor method was used to authenticate.
": "{String}",WindowSize
Required/mandatory field
The originating devices browser window size.
": "{String}"TestData
This field is optional.
": {GovTestScenarioHeader
sets the value for Gov-Test-Scenario header. the value 'default' signals to not set this header so as to recieve normal response from test enviroment.
Default value: default
This field is optional.
": "{String}"The query string is placed after the resource URL, seperated with a questionmark (?). The query string is composed of a series of query parameters with values. See the page about query parameters on how to use these parameters.
| vatPeriod Integer, optional |
Accounting period this VAT posting belongs to
Minimum: 190000, Maximum: 299999 |
| $access_token String, optional | After successful login you get an access token which needs to be provided in all API requests. Even though it is possible to pass this token as query parameter, we recommended passing it using the HTTP request header as described in Authorization. Note that all access tokens have an expiration time. |
| $db String, optional | Set the database/company for the request |
| $useMinimumVersion Integer, optional | Used to run a new version of an API resource when your API client is running a deprecated API resource. See the Breaking changes page for more information. |
| $lang String, optional | Specifies the language used in the response, following the 3-letter ISO-639-1 [lll] |
Read more about filters and sorting on how to use filter parameters and named filters.
Read more about filters and sorting on how to use sortable parameters
Requesting this resource will yield the following response. Mouse over fieldnames (or fieldgroups) for descriptions and other useful information about the fields.
Please note that some fields may be removed from the response, based on user roles/duties/permissions.
OperationInstanceId
Operation instance identifier
>{Integer}</OperationInstanceId>Status
Status of the instance, 2 = started, 7 = error, 9 = finished
>{Integer}</Status>CreatedAt
Date and time the operation instance was created
>{Datetime}</CreatedAt>CreatedBy
Reference to the creator
>UserId
User identifier
>{Integer}</UserId>UserLink
User reference
>{String}</UserLink>ObjectId
Identifier of the object
>{String}</ObjectId>ObjectType
Type of object
>{String}</ObjectType>ObjectLink
API reference to the object
>{String}</ObjectLink>ItemId
Item-number of the object
>{Integer}</ItemId>ItemType
Type of item
>{String}</ItemType>ItemLink
API reference to the item
>{String}</ItemLink>RamBaseKey
Internal RamBase identifier of the object/item
>{String}</RamBaseKey>ApiOprationId
Api operation identifiers
>{Integer}</ApiOprationId>ApiOperationLink
Api operation reference
>{String}</ApiOperationLink>ObjectId
Identifier of the object
>{String}</ObjectId>ObjectType
Type of object
>{String}</ObjectType>ObjectLink
API reference to the object
>{String}</ObjectLink>ItemId
Item-number of the object
>{Integer}</ItemId>ItemType
Type of item
>{String}</ItemType>ItemLink
API reference to the item
>{String}</ItemLink>RamBaseKey
Internal RamBase identifier of the object/item
>{String}</RamBaseKey>Message
Full error message/description. The message is generated from the specified ErrorMessage object, expanded with the given parameter(s).
>{String}</Message>TranslatedMessage
Full translated error description. The language used is specified either in $lang or by user settings. If error message don't exist in desired language, english will be used.
>{String}</TranslatedMessage>StackTrace
Stack trace for details about the error
>{String}</StackTrace>ErrorMessage
Contains a reference to the error message, if an error occured
>ErrorMessageId
Error message identifier
>{Integer}</ErrorMessageId>ErrorMessageLink
Error message reference
>{String}</ErrorMessageLink>Index
Error Key
>{Integer}</Index>Value
Value of the error parameter
>{String}</Value>Message
Full error message/description. The message is generated from the specified ErrorMessage object, expanded with the given parameter(s).
>{String}</Message>TranslatedMessage
Full translated error description. The language used is specified either in $lang or by user settings. If error message don't exist in desired language, english will be used.
>{String}</TranslatedMessage>StackTrace
Stack trace for details about the error
>{String}</StackTrace>ErrorMessage
Contains a reference to the error message, if an error occured
>ErrorMessageId
Error message identifier
>{Integer}</ErrorMessageId>ErrorMessageLink
Error message reference
>{String}</ErrorMessageLink>Index
Error Key
>{Integer}</Index>Value
Value of the error parameter
>{String}</Value>Key
Key of the result value
>{String}</Key>Value
Value of the result value
>{String}</Value>SystemJob
Contains a reference to the system job, if a system job was started
>ObjectId
{OIN.ObjectId}
>{Integer}</ObjectId>ObjectType
Type of object
>{String}</ObjectType>PercentComplete
Percent complete
>{Integer}</PercentComplete>ObjectLink
API reference to the object
>{String}</ObjectLink>OperationInstanceLink
Operation instance reference
>{String}</OperationInstanceLink>OperationInstanceId
Operation instance identifier
": "{Integer}",Status
Status of the instance, 2 = started, 7 = error, 9 = finished
": "{Integer}",CreatedAt
Date and time the operation instance was created
": "{Datetime}",CreatedBy
Reference to the creator
": {UserId
User identifier
": "{Integer}",UserLink
User reference
": "{String}"ObjectId
Identifier of the object
": "{String}",ObjectType
Type of object
": "{String}",ObjectLink
API reference to the object
": "{String}",ItemId
Item-number of the object
": "{Integer}",ItemType
Type of item
": "{String}",ItemLink
API reference to the item
": "{String}",RamBaseKey
Internal RamBase identifier of the object/item
": "{String}"ApiOprationId
Api operation identifiers
": "{Integer}",ApiOperationLink
Api operation reference
": "{String}"ObjectId
Identifier of the object
": "{String}",ObjectType
Type of object
": "{String}",ObjectLink
API reference to the object
": "{String}",ItemId
Item-number of the object
": "{Integer}",ItemType
Type of item
": "{String}",ItemLink
API reference to the item
": "{String}",RamBaseKey
Internal RamBase identifier of the object/item
": "{String}"Message
Full error message/description. The message is generated from the specified ErrorMessage object, expanded with the given parameter(s).
": "{String}",TranslatedMessage
Full translated error description. The language used is specified either in $lang or by user settings. If error message don't exist in desired language, english will be used.
": "{String}",StackTrace
Stack trace for details about the error
": "{String}",ErrorMessage
Contains a reference to the error message, if an error occured
": {ErrorMessageId
Error message identifier
": "{Integer}",ErrorMessageLink
Error message reference
": "{String}"Index
Error Key
": "{Integer}",Value
Value of the error parameter
": "{String}"Message
Full error message/description. The message is generated from the specified ErrorMessage object, expanded with the given parameter(s).
": "{String}",TranslatedMessage
Full translated error description. The language used is specified either in $lang or by user settings. If error message don't exist in desired language, english will be used.
": "{String}",StackTrace
Stack trace for details about the error
": "{String}",ErrorMessage
Contains a reference to the error message, if an error occured
": {ErrorMessageId
Error message identifier
": "{Integer}",ErrorMessageLink
Error message reference
": "{String}"Index
Error Key
": "{Integer}",Value
Value of the error parameter
": "{String}"Key
Key of the result value
": "{String}",Value
Value of the result value
": "{String}"SystemJob
Contains a reference to the system job, if a system job was started
": {ObjectId
{OIN.ObjectId}
": "{Integer}",ObjectType
Type of object
": "{String}",PercentComplete
Percent complete
": "{Integer}",ObjectLink
API reference to the object
": "{String}"OperationInstanceLink
Operation instance reference
": "{String}"
List of available operations/actions for this resource.
See the operations documentation for more information about API operations.
Possible error codes the response might return: