Raw REST examples

These REST examples demonstrate the data that is sent when you make a request.

Authenticate

You can make authentication requests with or without cookies. If you use the AP Essentials API SDK, you should use cookies for authentication. The SDK does not support cookieless authentication. Cookieless authentication is only available for uncommon cases where the AP Essentials API SDK is not used and cookieless authentication is required.

Authenticate with a cookie

POST https://services.readsoftonline.com/authentication/rest/authenticate HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip,deflate
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Content-Length: 73
Connection: Close

{"UserName":"myuser","Password":"mypassword","AuthenticationType":0}

Authenticate without a cookie

If you use the AP Essentials API SDK, you should use cookies for authentication. The SDK does not support cookieless authentication. Cookieless authentication is only available for uncommon cases where the AP Essentials API SDK is not used and cookieless authentication is required.

When you successfully authenticate without a cookie, the response includes an authentication token that is valid for 30 minutes. After 30 minutes, the client must call the Authenticate API endpoint again to receive a new token.

The following C# code demonstrates how to authenticate without using cookies and without using the API SDK.

class Program
{
  private static readonly Uri AuthUri =
      new Uri("https://services.readsoftonline.com/authentication/rest/authenticate");

  private static readonly Uri CurrentUserUri =
      new Uri("https://services.readsoftonline.com/users/rest/currentuser");

  private static string ApiKey = "11111111-2222-3333-4444-555555555555";

  private static void Main(string[] args)
  {
    Authenticate();
  }

  private static void Authenticate()
  {
    var loginRequest = (HttpWebRequest)WebRequest.Create(AuthUri);

    loginRequest.Accept = "application/xml";
    loginRequest.ContentType = "application/xml";
    loginRequest.Headers.Add("x-rs-key", ApiKey);
    loginRequest.Method = "POST";

    using (var request = loginRequest.GetRequestStream())
    using (var sr = new StreamWriter(request, Encoding.UTF8))
    {
      sr.Write("<AuthenticationCredentials>");
      sr.Write("<UserName>account_name</UserName>");
      sr.Write("<Password>account_password</Password>");
      sr.Write("<AuthenticationType>SetBodyToken</AuthenticationType>");
      sr.Write("</AuthenticationCredentials>");
    }

    string authenticationToken;

    using (var response = loginRequest.GetResponse())
    using (var responseStream = response.GetResponseStream())
    using (var streamReader = new StreamReader(responseStream, Encoding.UTF8))
    {
      var body = streamReader.ReadToEnd();

      var xmlDocument = new XmlDocument { XmlResolver = null };
      xmlDocument.LoadXml(body);

      authenticationToken = xmlDocument.SelectSingleNode("/AuthenticationResult/Token").InnerText;
    }

    var getCurrentUserRequest = (HttpWebRequest)WebRequest.Create(CurrentUserUri);
    getCurrentUserRequest.Accept = "application/xml";
    getCurrentUserRequest.ContentType = "application/xml";
    getCurrentUserRequest.Headers.Add("x-rs-key", ApiKey);
    getCurrentUserRequest.Headers.Add("Authorization", $"ApsToken Value=\"{authenticationToken}\"");
    getCurrentUserRequest.Method = "GET";

    using (var response = getCurrentUserRequest.GetResponse())
    using (var responseStream = response.GetResponseStream())
    using (var streamReader = new StreamReader(responseStream, Encoding.UTF8))
    {
      var body = streamReader.ReadToEnd();

      var xmlDocument = new XmlDocument { XmlResolver = null };
      xmlDocument.LoadXml(body);

      var fullName = xmlDocument.SelectSingleNode("/User2/FullName").InnerText;

      Console.WriteLine($"Hello {fullName}");
    }
  }
}

The code above produces this authentication request:

POST https://services.readsoftonline.com/authentication/rest/authenticate HTTP/1.1
Accept: application/xml
Content-Type: application/xml
x-rs-key: 11111111-2222-3333-4444-555555555555

<AuthenticationCredentials>
  <UserName>account_name</UserName>
  <Password>account_password</Password>
  <AuthenticationType>SetBodyToken</AuthenticationType>
</AuthenticationCredentials>

A successful response to the request above would look like this:

<AuthenticationResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Status>Success</Status>
  <RedirectUri i:nil="true"/>
  <Challange i:nil="true"/>
  <ClientDeviceSecret i:nil="true"/>
  <Token>secret-token</Token>
</AuthenticationResult>

After a successful authentication without a cookie, a request to get the current user would look like this:

GET https://services.readsoftonline.com/users/rest/currentuser HTTP/1.1
Accept: application/xml
Content-Type: application/xml
x-rs-key: 11111111-2222-3333-4444-555555555555
Authorization: ApsToken Value="secret-token"

Get current user response (body):

<User2 xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>22222222222222222222222222222222</Id>
  <OrganizationId>11111111111111111111111111111111</OrganizationId>
  <UserName>account_name</UserName>
  ....
</User2>

GetDocumentOutputData

POST https://services.readsoftonline.com/documents/rest/file/77d38d515ae6447ea2ef0465bd59c2d6/data HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip,deflate
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=33B1C66101611E8FBA7E38DFF2BC2C90288A09C9472963DDFB3EB8164D2BE1068CCFBD0C99A2A27D3B4C4D71B68061D1538986597BFFE7B822F95B34F17C712367D47B7CE683F557EC7CFDAA5906E70600757B7EF1DEC8CA1F3723B59894F878CCB4EF292E0F1319D52FE80B21FC180EA2B90F91C7C1CD4FBF0A5732DA6CE1229EBED0E05CD5A0D53DCBC86A6C5D35880DC182A3CD249A378FFE1060215BF969EA6C8D8ADEDEAA4DF530086EC87B5EC758B4353377BAFA4BAD4FC18C4AC4B55BD1475B5F7F000AB7EC803677BC9A42A9FB9388155481478420ED850E57B05A7A; 
x-rs-host=somepartner.readsoftonline.com
Content-Length: 2
Connection: Close
[]

GetDocumentOutputImage

GET https://services.readsoftonline.com/documents/rest/file/ccc5cae1ec0a47b89fb6fc3afee92d73/image HTTP/1.1
Accept: */*
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=127E5FA6CCB41269F4B814E6610B57BB3A9540188DDD424A26566FDAF9B8254D0A3B8A7257054383B6946BD17695CD041570CF29ED81A5F7508797D4E43307219B497EE647E7963C894F21F05AAE1081F373CF70F07B633E66C9B415C3C40B892CC2E074C131B80F4C524E93680963C569E0AA782E1B167210A47E72B0ACC682E2D1584DCC3568E3BBCE4DBC272FC2C0428DAC177B723CC56E6213F8E3E1AF7518A7E1664CBCBE7F786F3343CCF05CE939638D68938F13584153FB060E83C4A834D54D31CB7BE7D568D92029EF6190DAF8168D48C366300B33E6DE8611529DA8; 
x-rs-host=somepartner.readsoftonline.com
Accept-Encoding: gzip, deflate
Connection: Close

GetOutputDocuments

GET https://services.readsoftonline.com/documents/rest/customers/outputdocumentsbycurrentcustomer HTTP/1.1
Accept: */*
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=127E5FA6CCB41269F4B814E6610B57BB3A9540188DDD424A26566FDAF9B8254D0A3B8A7257054383B6946BD17695CD041570CF29ED81A5F7508797D4E43307219B497EE647E7963C894F21F05AAE1081F373CF70F07B633E66C9B415C3C40B892CC2E074C131B80F4C524E93680963C569E0AA782E1B167210A47E72B0ACC682E2D1584DCC3568E3BBCE4DBC272FC2C0428DAC177B723CC56E6213F8E3E1AF7518A7E1664CBCBE7F786F3343CCF05CE939638D68938F13584153FB060E83C4A834D54D31CB7BE7D568D92029EF6190DAF8168D48C366300B33E6DE8611529DA8; 
x-rs-host=somepartner.readsoftonline.com
Accept-Encoding: gzip, deflate
Connection: Close

UploadImage

POST https://services.readsoftonline.com/files/rest/image2?filename=BenningtonFax4.tif&customerid=68dd6ce8e9bb4fec8fedc43b49514d24&batchexternalid=&buyerid=68dd6ce8e9bb4fec8fedc43b49514d24&documenttype=SWEGE2&sortingmethod=OneDocumentPerFile HTTP/1.1
Content-Type: application/octet-stream
Accept: */*
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: d68c687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=E1F32D1F16BF04576E7B210722AF1B9920D5A0255874A80CCCDE5B8674F8701FA561B611A00998C90F8CB4B1A85682CDB1B553D7EA09A33F5B04AC54A28E64B43EA08163A5CD2B618222A04BC97E82D13F0C4835E0709388B8FF55775867C93F63B197F9E4AD7F11D64B419EEAD19623986AAC6B1528877A13B40CB76CBC089C7B001F391D7B05C59CCD0D118755DAB27737FFC5BC268E10DF9E34C8945DD76B23F490CCC7C4674C670A54BEE9EF736B49B9E30EE7F9FFECE173C8AA72BF94481DF6B5ECBA1B55A8676679842A70499B712D0F315819F42BA179D924E0E202DB; 
x-rs-host=somepartner.readsoftonline.com
Content-Length: 19838
Accept-Encoding: gzip, deflate
Connection: Close

binary image data...]

Select here to see the example with actual binary image data.

UploadMasterDataObjects

PUT https://services.readsoftonline.com/masterdata/rest/88dd6ce8e9bb4fec8fedc43b49514d24/masterdataobjects/Department HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip,deflate
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=E5C93B76034307BB869F136174C1B3C85EAD045AFB135B2F84A032BCAA84DE65DC45DC57932BCB57CAA1C387C4215C5089911B77FE5FDFA4EEB34B87A6B142F85ABC27545877E9C983952E200C67704BCE1436CB91E3429AAC474896D452DDE6C316B70EABE48B777B4AE4A2431CE8D4F95FD56CAB42C737108E18C0D25DA50592CE8D9CAF94A81544D667FD04D3EE2302126794AEDD0F4B5D73933F80FCC9193DD3ED45D6155697CA24FAD219B12EFCDD1060C7AB839C0DE99183604AFCBED5DEB1C055327AB958EF8601FE86B747E2B8AB540610E8A2E7637C30F93FCB6E9F; 
x-rs-host=somepartner.readsoftonline.com
Content-Length: 201
Connection: Close

[{"Value":"DPA001","Name":"IT","Description":null,"Active":true},{"Value":"DPB002","Name":"Finance","Description":null,"Active":true},{"Value":"DPC003","Name":"Sales","Description":null,"Active":true}]

UploadSuppliers

PUT https://services.readsoftonline.com/masterdata/rest/88dd6ce8e9bb4fec8fedc43b49514d24/suppliers HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip,deflate
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=E5C93B76034307BB869F136174C1B3C85EAD045AFB135B2F84A032BCAA84DE65DC45DC57932BCB57CAA1C387C4215C5089911B77FE5FDFA4EEB34B87A6B142F85ABC27545877E9C983952E200C67704BCE1436CB91E3429AAC474896D452DDE6C316B70EABE48B777B4AE4A2431CE8D4F95FD56CAB42C737108E18C0D25DA50592CE8D9CAF94A81544D667FD04D3EE2302126794AEDD0F4B5D73933F80FCC9193DD3ED45D6155697CA24FAD219B12EFCDD1060C7AB839C0DE99183604AFCBED5DEB1C055327AB958EF8601FE86B747E2B8AB540610E8A2E7637C30F93FCB6E9F; 
x-rs-host=somepartner.readsoftonline.com
Content-Length: 1238
Connection: Close

[{"SupplierNumber":"1001","Name":"Anconia Corp","Description":null,"TaxRegistrationNumber":null,"OrganizationNunmber":null,"Street":null,"PostalCode":null,"City":null,"CountryName":null,"PaymentTerm":null,"PaymentMethod":null,"CurrencyCode":null,"Id":null,"Location":null,"State":null,"BankAccounts":[]},{"SupplierNumber":"1002","Name":"Veiraoou Groygguoo Company","Description":null,"TaxRegistrationNumber":null,"OrganizationNunmber":null,"Street":null,"PostalCode":null,"City":null,"CountryName":null,"PaymentTerm":null,"PaymentMethod":null,"CurrencyCode":null,"Id":null,"Location":null,"State":null,"BankAccounts":[]},{"SupplierNumber":"1003","Name":"Raxaf Negooo Limited","Description":null,"TaxRegistrationNumber":null,"OrganizationNunmber":null,"Street":null,"PostalCode":null,"City":null,"CountryName":null,"PaymentTerm":null,"PaymentMethod":null,"CurrencyCode":null,"Id":null,"Location":null,"State":null,"BankAccounts":[]},{"SupplierNumber":"1004","Name":"Polychemtex Inc","Description":null,"TaxRegistrationNumber":null,"OrganizationNunmber":null,"Street":null,"PostalCode":null,"City":null,"CountryName":null,"PaymentTerm":null,"PaymentMethod":null,"CurrencyCode":null,"Id":null,"Location":null,"State":null,"BankAccounts":[]}]