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].

  1. Delete a single revision: [DELETE] /Employer/ER001/2017-07-15
  2. 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'