Managing the Employer
The employer data object represents the company level entity. Company level values are set here.
The Employer is a revisible object.
See the [Reference Data] for a complete breakdown of all the employer properties.
Supported HTTP methods are:
[GET] an Employer
This example demonstrates how to [GET] an existing employer instance.
Revisible objects support [GET] with an effective date. This allows revisions to be selected by date.
Effective date example: /Employer/ER001/2017-04-06
curl -X GET \
'https://api.test.payrun.io/Employers' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml'
curl -X GET \
'https://api.test.payrun.io/Employers' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json'
Response Example
<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2016-01-01</EffectiveDate>
<Revision>1</Revision>
<Name>Employer A001 Ltd</Name>
<Region>England</Region>
<Territory>UnitedKingdom</Territory>
<BacsServiceUserNumber>123456</BacsServiceUserNumber>
<RuleExclusions>None</RuleExclusions>
<ClaimEmploymentAllowance>false</ClaimEmploymentAllowance>
<ClaimSmallEmployerRelief>false</ClaimSmallEmployerRelief>
<ApprenticeshipLevyAllowance>1234.0000</ApprenticeshipLevyAllowance>
<Address>
<Address1>House</Address1>
<Address2>Street</Address2>
<Address3>Town</Address3>
<Address4>County</Address4>
<Postcode>TE1 1ST</Postcode>
<Country>United Kingdom</Country>
</Address>
<HmrcSettings>
<TaxOfficeNumber>451</TaxOfficeNumber>
<TaxOfficeReference>A451</TaxOfficeReference>
<AccountingOfficeRef>123PA1234567X</AccountingOfficeRef>
<Sender>Employer</Sender>
<SenderId>ISV451</SenderId>
<Password>a3MweCsv60kkAgzEpXeCqQ==</Password>
<ContactFirstName>Joe</ContactFirstName>
<ContactLastName>Bloggs</ContactLastName>
<ContactEmail>Jow.Bloggs@PayRunIO.co.uk</ContactEmail>
<ContactTelephone>01234567890</ContactTelephone>
<ContactFax>01234567890</ContactFax>
</HmrcSettings>
<BankAccount>
<AccountName>Getting St</AccountName>
<AccountNumber>12345678</AccountNumber>
<SortCode>012345</SortCode>
</BankAccount>
</Employer>
{
"Employer": {
"EffectiveDate": "2016-01-01",
"Revision": "1",
"Name": "Employer A001 Ltd",
"Region": "England",
"Territory": "UnitedKingdom",
"BacsServiceUserNumber": "123456",
"RuleExclusions": "None",
"ClaimEmploymentAllowance": "false",
"ClaimSmallEmployerRelief": "false",
"ApprenticeshipLevyAllowance": "1234.0000",
"Address": {
"Address1": "House",
"Address2": "Street",
"Address3": "Town",
"Address4": "County",
"Postcode": "TE1 1ST",
"Country": "United Kingdom"
},
"HmrcSettings": {
"TaxOfficeNumber": "451",
"TaxOfficeReference": "A451",
"AccountingOfficeRef": "123PA1234567X",
"Sender": "Employer",
"SenderId": "ISV451",
"Password": "a3MweCsv60kkAgzEpXeCqQ==",
"ContactFirstName": "Joe",
"ContactLastName": "Bloggs",
"ContactEmail": "Jow.Bloggs@PayRunIO.co.uk",
"ContactTelephone": "01234567890",
"ContactFax": "01234567890"
},
"BankAccount": {
"AccountName": "Getting St",
"AccountNumber": "12345678",
"SortCode": "012345"
}
}
}
[POST] a new Employer
This example demonstrates creating a new employer using a [POST].
When performing a [POST] the API will generate default resource location unique keys.
Default employer unique key pattern is:
- ER001
- ER002
- etc...
curl -X POST \
'https://api.test.payrun.io/Employers' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml' \
-d '<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2016-01-01</EffectiveDate>
<Revision>0</Revision>
<Name>Employer A001 Ltd</Name>
<Region>England</Region>
<Territory>UnitedKingdom</Territory>
<BacsServiceUserNumber>123456</BacsServiceUserNumber>
<RuleExclusions>None</RuleExclusions>
<ClaimEmploymentAllowance>false</ClaimEmploymentAllowance>
<ClaimSmallEmployerRelief>false</ClaimSmallEmployerRelief>
<ApprenticeshipLevyAllowance>1234.0000</ApprenticeshipLevyAllowance>
<Address>
<Address1>House</Address1>
<Address2>Street</Address2>
<Address3>Town</Address3>
<Address4>County</Address4>
<Postcode>TE1 1ST</Postcode>
<Country>United Kingdom</Country>
</Address>
<HmrcSettings>
<TaxOfficeNumber>451</TaxOfficeNumber>
<TaxOfficeReference>A451</TaxOfficeReference>
<AccountingOfficeRef>123PA1234567X</AccountingOfficeRef>
<Sender>Employer</Sender>
<SenderId>ISV451</SenderId>
<Password>a3MweCsv60kkAgzEpXeCqQ==</Password>
<ContactFirstName>Joe</ContactFirstName>
<ContactLastName>Bloggs</ContactLastName>
<ContactEmail>Jow.Bloggs@PayRunIO.co.uk</ContactEmail>
<ContactTelephone>01234567890</ContactTelephone>
<ContactFax>01234567890</ContactFax>
</HmrcSettings>
<BankAccount>
<AccountName>Getting St</AccountName>
<AccountNumber>12345678</AccountNumber>
<SortCode>012345</SortCode>
</BankAccount>
</Employer>'
curl -X POST \
'https://api.test.payrun.io/Employers' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
"Employer": {
"EffectiveDate": "2016-01-01",
"Revision": "0",
"Name": "Employer A001 Ltd",
"Region": "England",
"Territory": "UnitedKingdom",
"BacsServiceUserNumber": "123456",
"RuleExclusions": "None",
"ClaimEmploymentAllowance": "false",
"ClaimSmallEmployerRelief": "false",
"ApprenticeshipLevyAllowance": "1234.0000",
"Address": {
"Address1": "House",
"Address2": "Street",
"Address3": "Town",
"Address4": "County",
"Postcode": "TE1 1ST",
"Country": "United Kingdom"
},
"HmrcSettings": {
"TaxOfficeNumber": "451",
"TaxOfficeReference": "A451",
"AccountingOfficeRef": "123PA1234567X",
"Sender": "Employer",
"SenderId": "ISV451",
"Password": "a3MweCsv60kkAgzEpXeCqQ==",
"ContactFirstName": "Joe",
"ContactLastName": "Bloggs",
"ContactEmail": "Jow.Bloggs@PayRunIO.co.uk",
"ContactTelephone": "01234567890",
"ContactFax": "01234567890"
},
"BankAccount": {
"AccountName": "Getting St",
"AccountNumber": "12345678",
"SortCode": "012345"
}
}
}'
Response Example
The [POST] response is a link to the newly generated resource.
<?xml version="1.0"?>
<Link
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
title="ER001"
href="/Employer/ER001"
rel="Employer"
/>
{
"Link": {
"@title": "ER127",
"@href": "/Employer/ER001",
"@rel": "Employer"
}
}
[PUT] an Employer
This example demonstrates creating a new employer using [PUT]. You can use [PUT] to create new and updated existing objects.
When performing a [PUT] you specify the resource location unique key.
This allows you to use your own resource managment naming conventions.
Example:
- /Employer/MyEmployerKey
- /Employer/AnotherEmployerKey
curl -X PUT \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml' \
-d '<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2016-01-01</EffectiveDate>
<Revision>0</Revision>
<Name>Employer A001 Ltd</Name>
<Region>England</Region>
<Territory>UnitedKingdom</Territory>
<BacsServiceUserNumber>123456</BacsServiceUserNumber>
<RuleExclusions>None</RuleExclusions>
<ClaimEmploymentAllowance>false</ClaimEmploymentAllowance>
<ClaimSmallEmployerRelief>false</ClaimSmallEmployerRelief>
<ApprenticeshipLevyAllowance>1234.0000</ApprenticeshipLevyAllowance>
<Address>
<Address1>House</Address1>
<Address2>Street</Address2>
<Address3>Town</Address3>
<Address4>County</Address4>
<Postcode>TE1 1ST</Postcode>
<Country>United Kingdom</Country>
</Address>
<HmrcSettings>
<TaxOfficeNumber>451</TaxOfficeNumber>
<TaxOfficeReference>A451</TaxOfficeReference>
<AccountingOfficeRef>123PA1234567X</AccountingOfficeRef>
<Sender>Employer</Sender>
<SenderId>ISV451</SenderId>
<Password>a3MweCsv60kkAgzEpXeCqQ==</Password>
<ContactFirstName>Joe</ContactFirstName>
<ContactLastName>Bloggs</ContactLastName>
<ContactEmail>Jow.Bloggs@PayRunIO.co.uk</ContactEmail>
<ContactTelephone>01234567890</ContactTelephone>
<ContactFax>01234567890</ContactFax>
</HmrcSettings>
<BankAccount>
<AccountName>Getting St</AccountName>
<AccountNumber>12345678</AccountNumber>
<SortCode>012345</SortCode>
</BankAccount>
</Employer>'
curl -X PUT \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
"Employer": {
"EffectiveDate": "2016-01-01",
"Revision": "0",
"Name": "Employer A001 Ltd",
"Region": "England",
"Territory": "UnitedKingdom",
"BacsServiceUserNumber": "123456",
"RuleExclusions": "None",
"ClaimEmploymentAllowance": "false",
"ClaimSmallEmployerRelief": "false",
"ApprenticeshipLevyAllowance": "1234.0000",
"Address": {
"Address1": "House",
"Address2": "Street",
"Address3": "Town",
"Address4": "County",
"Postcode": "TE1 1ST",
"Country": "United Kingdom"
},
"HmrcSettings": {
"TaxOfficeNumber": "451",
"TaxOfficeReference": "A451",
"AccountingOfficeRef": "123PA1234567X",
"Sender": "Employer",
"SenderId": "ISV451",
"Password": "a3MweCsv60kkAgzEpXeCqQ==",
"ContactFirstName": "Joe",
"ContactLastName": "Bloggs",
"ContactEmail": "Jow.Bloggs@PayRunIO.co.uk",
"ContactTelephone": "01234567890",
"ContactFax": "01234567890"
},
"BankAccount": {
"AccountName": "Getting St",
"AccountNumber": "12345678",
"SortCode": "012345"
}
}
}'
Response Example
The [PUT] response is the entire updated resource.
<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2016-01-01</EffectiveDate>
<Revision>1</Revision>
<Name>Employer A001 Ltd</Name>
<Region>England</Region>
<Territory>UnitedKingdom</Territory>
<BacsServiceUserNumber>123456</BacsServiceUserNumber>
<RuleExclusions>None</RuleExclusions>
<ClaimEmploymentAllowance>false</ClaimEmploymentAllowance>
<ClaimSmallEmployerRelief>false</ClaimSmallEmployerRelief>
<ApprenticeshipLevyAllowance>1234.0000</ApprenticeshipLevyAllowance>
<Address>
<Address1>House</Address1>
<Address2>Street</Address2>
<Address3>Town</Address3>
<Address4>County</Address4>
<Postcode>TE1 1ST</Postcode>
<Country>United Kingdom</Country>
</Address>
<HmrcSettings>
<TaxOfficeNumber>451</TaxOfficeNumber>
<TaxOfficeReference>A451</TaxOfficeReference>
<AccountingOfficeRef>123PA1234567X</AccountingOfficeRef>
<Sender>Employer</Sender>
<SenderId>ISV451</SenderId>
<Password>a3MweCsv60kkAgzEpXeCqQ==</Password>
<ContactFirstName>Joe</ContactFirstName>
<ContactLastName>Bloggs</ContactLastName>
<ContactEmail>Jow.Bloggs@PayRunIO.co.uk</ContactEmail>
<ContactTelephone>01234567890</ContactTelephone>
<ContactFax>01234567890</ContactFax>
</HmrcSettings>
<BankAccount>
<AccountName>Getting St</AccountName>
<AccountNumber>12345678</AccountNumber>
<SortCode>012345</SortCode>
</BankAccount>
</Employer>
{
"Employer": {
"EffectiveDate": "2016-01-01",
"Revision": "1",
"Name": "Employer A001 Ltd",
"Region": "England",
"Territory": "UnitedKingdom",
"BacsServiceUserNumber": "123456",
"RuleExclusions": "None",
"ClaimEmploymentAllowance": "false",
"ClaimSmallEmployerRelief": "false",
"ApprenticeshipLevyAllowance": "1234.0000",
"Address": {
"Address1": "House",
"Address2": "Street",
"Address3": "Town",
"Address4": "County",
"Postcode": "TE1 1ST",
"Country": "United Kingdom"
},
"HmrcSettings": {
"TaxOfficeNumber": "451",
"TaxOfficeReference": "A451",
"AccountingOfficeRef": "123PA1234567X",
"Sender": "Employer",
"SenderId": "ISV451",
"Password": "a3MweCsv60kkAgzEpXeCqQ==",
"ContactFirstName": "Joe",
"ContactLastName": "Bloggs",
"ContactEmail": "Jow.Bloggs@PayRunIO.co.uk",
"ContactTelephone": "01234567890",
"ContactFax": "01234567890"
},
"BankAccount": {
"AccountName": "Getting St",
"AccountNumber": "12345678",
"SortCode": "012345"
}
}
}
[PATCH] an Employer
This example demonstrates updating an existing employer using [PATCH].
[PATCH] allows updates by supplying only the changes.
Creates and returns a new object revision including the specified changes.
curl -X PATCH \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml' \
-d '<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2016-02-01</EffectiveDate>
<Name>Employer A002 Ltd</Name>
<ApprenticeshipLevyAllowance>1234.0000</ApprenticeshipLevyAllowance>
<Address>
<Address1>House 2</Address1>
<Address2>Street 2</Address2>
<Address3>Town 2</Address3>
<Address4>County 2</Address4>
<Postcode>TE2 2ST</Postcode>
<Country>United Kingdom</Country>
</Address>
</Employer>'
curl -X PATCH \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
"Employer": {
"EffectiveDate": "2016-02-01",
"Name": "Employer A002 Ltd",
"Address": {
"Address1": "House 2",
"Address2": "Street 2",
"Address3": "Town 2",
"Address4": "County 2",
"Postcode": "TE2 2ST",
"Country": "United Kingdom 2"
}
}
}'
Response Example
The [PATCH] response is the entire updated resource.
<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2016-02-01</EffectiveDate>
<Revision>3</Revision>
<Name>Employer A002 Ltd</Name>
<Region>England</Region>
<Territory>UnitedKingdom</Territory>
<BacsServiceUserNumber>123456</BacsServiceUserNumber>
<RuleExclusions>None</RuleExclusions>
<ClaimEmploymentAllowance>false</ClaimEmploymentAllowance>
<ClaimSmallEmployerRelief>false</ClaimSmallEmployerRelief>
<ApprenticeshipLevyAllowance>1234.0000</ApprenticeshipLevyAllowance>
<Address>
<Address1>House 2</Address1>
<Address2>Street 2</Address2>
<Address3>Town 2</Address3>
<Address4>County 2</Address4>
<Postcode>TE2 2ST</Postcode>
<Country>United Kingdom 2</Country>
</Address>
<HmrcSettings>
<TaxOfficeNumber>451</TaxOfficeNumber>
<TaxOfficeReference>A451</TaxOfficeReference>
<AccountingOfficeRef>123PA1234567X</AccountingOfficeRef>
<Sender>Employer</Sender>
<SenderId>ISV451</SenderId>
<Password>cb1MhtzuGzKpJdLzJG9vug==</Password>
<ContactFirstName>Joe</ContactFirstName>
<ContactLastName>Bloggs</ContactLastName>
<ContactEmail>Jow.Bloggs@PayRunIO.co.uk</ContactEmail>
<ContactTelephone>01234567890</ContactTelephone>
<ContactFax>01234567890</ContactFax>
</HmrcSettings>
<BankAccount>
<AccountName>Getting St</AccountName>
<AccountNumber>12345678</AccountNumber>
<SortCode>012345</SortCode>
</BankAccount>
</Employer>
{
"Employer": {
"EffectiveDate": "2016-02-01",
"Revision": "3",
"Name": "Employer A002 Ltd",
"Region": "England",
"Territory": "UnitedKingdom",
"BacsServiceUserNumber": "123456",
"RuleExclusions": "None",
"ClaimEmploymentAllowance": "false",
"ClaimSmallEmployerRelief": "false",
"ApprenticeshipLevyAllowance": "1234",
"Address": {
"Address1": "House 2",
"Address2": "Street 2",
"Address3": "Town 2",
"Address4": "County 2",
"Postcode": "TE2 2ST",
"Country": "United Kingdom 2"
},
"HmrcSettings": {
"TaxOfficeNumber": "451",
"TaxOfficeReference": "A451",
"AccountingOfficeRef": "123PA1234567X",
"Sender": "Employer",
"SenderId": "ISV451",
"Password": "cb1MhtzuGzKpJdLzJG9vug==",
"ContactFirstName": "Joe",
"ContactLastName": "Bloggs",
"ContactEmail": "Jow.Bloggs@PayRunIO.co.uk",
"ContactTelephone": "01234567890",
"ContactFax": "01234567890"
},
"BankAccount": {
"AccountName": "Getting St",
"AccountNumber": "12345678",
"SortCode": "012345"
}
}
}
[DELETE] an Employer
This example demonstrates deleting an employer using the [DELETE] verb.
Revisable objects support 2 levels of [DELETE].
- Delete a single revision: [DELETE] /Employer/ER001/2017-07-15
- Delete the entire object: [DELETE] /Employer/ER001
curl -X DELETE \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml'
curl -X DELETE \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json'