With our community of partners, you can get expert advice and training so you can be up and running in no time! SETUP PARTNERS

API Documentation

Client Methods

Method Description
GET list Return a list of all clients
GET search Return a list of all clients matching search query
GET get/[uuid] Detailed information for a specific client
POST add Add a client and contacts
PUT update Update a clients details
PUT archive Archive a client
POST delete Delete a client
GET contact/[uuid] Detailed information for a specific contact
PUT contact/[uuid] Update a contacts details
POST contact add a contact to a client
DELETE contact/[uuid] delete a contact
GET documents/[uuid] Return a list of documents for a client
POST document Add a document to a client
POST addrelationship Add a relationship between clients (Practice Manager only)
POST updaterelationship Update the relationship details between clients (Practice Manager only)
POST deleterelationship Delete the relationship between clients (Practice Manager only)

GET list

Return a list of all clients

Parameters

Parameter Required? Description
detailed=true Optional Return detailed information of client. See GET get/[identifier] method for example of detailed client response.
modifiedsince=yyyy-MM-ddTHH:mm:ss Optional Return clients modified since a particular date (UTC), e.g. 2012-06-05T06:00:00

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/list

Example Response

<Response>
  <Status>OK</Status> 
  <Clients>
    <!-- Refer get/[identifier] method for full list of client fields  -->
    <Client>
      <UUID>c257b062-fbc9-4dc7-9132-f18ee956c4f9</UUID>
      <Name>XYZ Australia, NZ Business Unit</Name>
      <Title /> <!-- AU Tax Enabled only-->
      <Gender /> <!-- AU Tax Enabled only-->
      <FirstName /> <!-- for individuals only -->
      <LastName /> <!-- for individuals only -->
      <OtherName /> <!-- for individuals only -->
      <Email>someone@example.com</Email> 
      <DateOfBirth>1970-11-26T00:00:00</DateOfBirth> 
      <Address /> 
      <City /> 
      <Region /> 
      <PostCode /> 
      <Country /> 
      <PostalAddress>
         Level 32, PWC Building 
         188 Quay Street
         Auckland Central
      </PostalAddress> 
      <PostalCity>Auckland</PostalCity> 
      <PostalRegion /> 
      <PostalPostCode>1001</PostalPostCode>  
      <PostalCountry /> 
      <Phone>(02) 1723 5265</Phone>
      <Fax /> 
      <Website /> 
      <ReferralSource />
      <ExportCode />
      <IsProspect>No</IsProspect>
      <IsArchived>No</IsArchived>
      <IsDeleted>No</IsDeleted>
      <AccountManager>
        <UUID>f1ec264f-d269-4232-9615-c167583fa7da</UUID>
        <Name>Jo Blogs</Name> 
      </AccountManager>
      <Type>
        <Name>20th of Month</Name> 
        <CostMarkup>30.00</CostMarkup> 
        <PaymentTerm>DayOfMonth</PaymentTerm>  <!-- DayOfMonth or WithinDays  -->
        <PaymentDay>20</PaymentDay> 
      </Type>
      <Contacts>
        <Contact>
          <UUID>f1ec264f-d269-4232-9615-c167583fa7da</UUID>
          <IsPrimary>yes</IsPrimary>
          <Name>Samantha Benecke</Name> 
          <Salutation>Sam</Salutation> 
          <Addressee>Mrs S Benecke</Addressee> 
          <Mobile /> 
          <Email /> 
          <Phone /> 
          <Position /> 
        </Contact>
      </Contacts>
    </Client>
    <Client>
      <UUID>a5341eb9-c5be-4aae-881b-4ebc9933d5fb</UUID>
      <Name>A. Dutchess</Name> 
      <Address /> 
      <City /> 
      <Region /> 
      <PostCode /> 
      <Country /> 
      <PostalAddress>P O Box 123</PostalAddress> 
      <PostalCity>Wellington</PostalCity> 
      <PostalRegion /> 
      <PostalPostCode>6011</PostalPostCode>  
      <PostalCountry />
      <Phone /> 
      <Fax /> 
      <Website /> 
      <Contacts /> 
      <BillingClient>
        <UUID>e41ecd7a-ac85-4473-a7b3-052bd670f01e</UUID>
        <Name>Billing Client</Name>
      </BillingClient>
    </Client>
  </Clients>
</Response>

Return a list of all clients matching search query

Parameters

Parameter Required? Description
detailed=true Optional Return detailed information of client. See GET get/[identifier] method for example of detailed client response.

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/search?query=XYZ

Example Response

<Response>
  <Status>OK</Status> 
  <Clients>
    <Client>
      <UUID>c257b062-fbc9-4dc7-9132-f18ee956c4f9</UUID>
      <Name>XYZ Australia, NZ Business Unit</Name> 
      <Email>someone@example.com</Email> 
      <DateOfBirth>1970-11-26</DateOfBirth>
      <Address /> 
      <City /> 
      <Region /> 
      <PostCode /> 
      <Country /> 
      <PostalAddress>
         Level 32, PWC Building 
         188 Quay Street
         Auckland Central
      </PostalAddress> 
      <PostalCity>Auckland</PostalCity> 
      <PostalRegion /> 
      <PostalPostCode>1001</PostalPostCode>  
      <PostalCountry /> 
      <Phone>(02) 1723 5265</Phone>
      <Fax /> 
      <Website /> 
      <ReferralSource />
      <ExportCode />
      <IsProspect>No</IsProspect> 
      <AccountManager>
        <UUID>f1ec264f-d269-4232-9615-c167583fa7da</UUID>
        <Name>Jo Blogs</Name> 
      </AccountManager>
      <Type>
        <Name>20th of Month</Name> 
        <CostMarkup>30.00</CostMarkup> 
        <PaymentTerm>DayOfMonth</PaymentTerm>  <!-- DayOfMonth or WithinDays  -->
        <PaymentDay>20</PaymentDay> 
      </Type>
      <Contacts>
        <Contact>
          <UUID>f1ec264f-d269-4232-9615-c167583fa7da</UUID>
          <IsPrimary>yes</IsPrimary>
          <Name>Samantha Benecke</Name> 
          <Salutation>Sam</Salutation> 
          <Addressee>Mrs S Benecke</Addressee> 
          <Mobile /> 
          <Email /> 
          <Phone /> 
          <Position /> 
        </Contact>
      </Contacts>
    </Client>
    <Client>
      <UUID>a5341eb9-c5be-4aae-881b-4ebc9933d5fb</UUID>
      <Name>XYZ Dutchess</Name> 
      <Address /> 
      <City /> 
      <Region /> 
      <PostCode /> 
      <Country /> 
      <PostalAddress>P O Box 123</PostalAddress> 
      <PostalCity>Wellington</PostalCity> 
      <PostalRegion /> 
      <PostalPostCode>6011</PostalPostCode>  
      <PostalCountry /> 
      <Phone /> 
      <Fax /> 
      <Website /> 
      <Contacts /> 
      <BillingClient /> 
    </Client>
  </Clients>
</Response>

GET get/[uuid]

Detailed information for a specific client

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/get/c257b062-fbc9-4dc7-9132-f18ee956c4f9

Example Response

<Response>
  <Status>OK</Status>
  <Client>
    <UUID>c257b062-fbc9-4dc7-9132-f18ee956c4f9</UUID>
    <Name>Acmer Pty Ltd</Name> 
    <Email>someone@example.com</Email> 
    <DateOfBirth>1970-11-26</DateOfBirth> 
    <Address /> 
    <City /> 
    <Region /> 
    <PostCode /> 
    <Country /> 
    <PostalAddress>
       Level 32, PWC Building 
       188 Quay Street
       Auckland Central
    </PostalAddress> 
    <PostalCity>Auckland</PostalCity> 
    <PostalRegion /> 
    <PostalPostCode>1001</PostalPostCode>  
    <PostalCountry /> 
    <Phone>(02) 1723 5265</Phone> 
    <Fax /> 
    <Website /> 
    <ReferralSource />
    <ExportCode />
    <IsProspect>No</IsProspect> 
    <AccountManager>
      <UUID>ab3d6db0-f0be-4a3e-bd68-8fad1c6b40bb</UUID>
      <Name>Jo Blogs</Name> 
    </AccountManager>
    <Type>
      <Name>20th of Month</Name> 
      <CostMarkup>30.00</CostMarkup> 
      <PaymentTerm>DayOfMonth</PaymentTerm>  <!-- DayOfMonth or WithinDays  -->
      <PaymentDay>20</PaymentDay> 
    </Type>
    <Contacts>
      <Contact>
        <UUID>f1ec264f-d269-4232-9615-c167583fa7da</UUID>
        <IsPrimary>yes</IsPrimary>
        <Name>Wyett E Coyote</Name> 
        <Salutation /> 
        <Addressee /> 
        <Mobile /> 
        <Email /> 
        <Phone /> 
        <Position /> 
      </Contact>
    </Contacts>
     <Notes>
      <Note>
        <Title>note title</Title> 
        <Text>subject of the note</Text> 
        <Folder /> 
        <Date>2008-09-12T13:00:00</Date> 
        <CreatedBy>Jo Bloggs</CreatedBy>
      </Note>
    </Notes>
    <BillingClient>
      <UUID>e41ecd7a-ac85-4473-a7b3-052bd670f01e</UUID>
      <Name>Billing Client</Name>
    </BillingClient>

    <!-- The following fields are returned if the Practice Management module is enabled -->

    <JobManager>
      <UUID>ebc0e2ae-3d3e-4546-9787-8c659e445d31</UUID>
      <Name>John Smith</Name> 
    </JobManager>
    <FirstName />  <!-- Individual Only -->    
    <LastName />   <!-- Individual Only -->
    <OtherName />  <!-- Individual Only -->
    <DateOfBirth />  <!-- Individual Only -->


    <TaxNumber />   ******123  <!-- e.g. where the tax number is masked with *** except last 3 digits -->
    <CompanyNumber /> 
    <BusinessNumber /> 
    <BusinessStructure />   <!-- e.g. Individual, Company, Trust, etc  -->
    <BalanceMonth /> 
    <PrepareGST />   <!-- Yes or No -->
    <GSTRegistered />   <!-- Yes or No -->
    <GSTPeriod />  <!-- Monthly, 2 Monthly, 6 Monthly  -->
    <GSTBasis />  <!-- Invoice, Payment, Hybrid  -->
    <ProvisionalTaxBasis />  <!-- Standard Option, Estimate Option, Ratio Option  -->
    <ProvisionalTaxRatio /> 
    <!-- The following fields apply to NZ clients only -->
    <SignedTaxAuthority />  <!-- Yes or No -->
    <TaxAgent /> 
    <AgencyStatus />  <!-- With EOT, Without EOT, Unlinked -->
    <ReturnType />  <!-- IR3, IR3NR, IR4, IR6, IR7, IR9, PTS  -->

    <!-- The following fields apply to AU clients only -->
    <PrepareActivityStatement />  <!-- Yes or No -->
    <PrepareTaxReturn />  <!-- Yes or No -->


    <Groups>
      <Group>
        <UUID>9c3abe09-6df2-4f18-8090-36a44e91a1c3</UUID>
        <Name>Bloggs Family</Name>   
      </Group>
    </Groups>

    <Relationships>
      <Relationship>
        <UUID>9c3abe09-6df2-4f18-8090-36a44e91a1c3</UUID> 
        <Type>Shareholder</Type>   
        <RelatedClient>
          <UUID>651ec79a-93cb-458c-b5ca-e123c92192b6</UUID>  
          <Name>Bloggs Ltd</Name>   
        </RelatedClient>
        <NumberOfShares>1000</NumberOfShares>  <!-- Only set for Shareholder and Owner relationships -->   
        <Percentage>0</Percentage>  <!-- Only set for Partnership relationships-->
        <StartDate>2011-01-01</StartDate>
        <EndDate>2013-03-31</EndDate>
      </Relationship>
    </Relationships>

  </Client>
</Response>

POST add

Add a client and contacts

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/add

Example Message

<Client>
  <Name>Bloggs Electrical Ltd</Name>
  <Email></Email>  <!-- optional -->   
  <Address></Address>  <!-- optional -->   
  <City></City>  <!-- optional -->   
  <Region></Region>  <!-- optional -->   
  <PostCode></PostCode>  <!-- optional -->   
  <Country></Country>  <!-- optional -->   
  <PostalAddress></PostalAddress>  <!-- optional -->   
  <PostalCity></PostalCity>  <!-- optional -->   
  <PostalRegion></PostalRegion>  <!-- optional -->   
  <PostalPostCode></PostalPostCode>  <!-- optional -->   
  <PostalCountry></PostalCountry>  <!-- optional -->   
  <Phone></Phone>  <!-- optional -->   
  <Fax></Fax>  <!-- optional -->   
  <WebSite></WebSite>  <!-- optional -->   
  <ReferralSource></ReferralSource>  <!-- optional -->   
  <ExportCode></ExportCode>  <!-- optional --> 
  <IsProspect>No</IsProspect>    <!-- Yes | No --> 
  <AccountManagerUUID />  <!-- optional - UUID of staff member -->
  <Contacts>
    <Contact>
      <Name>Jo Bloggs</Name>
      <IsPrimary>yes</IsPrimary> <!-- If multiple contacts defined, method will interpret last primary client as Primary -->   
      <Salutation></Salutation>  <!-- optional -->   
      <Addressee></Addressee>  <!-- optional -->   
      <Phone></Phone>  <!-- optional -->   
      <Mobile></Mobile>  <!-- optional -->   
      <Email></Email>  <!-- optional -->   
      <Position></Position>  <!-- optional -->   
    </Contact>
  </Contacts>
  <BillingClientUUID /> <!-- optional UUID of billing client -->

  <!-- The following fields are only applicable if the Practice Management module is enabled -->

  <FirstName />   <!-- optional, for individuals only -->   
  <LastName />   <!-- optional, for individuals only -->   
  <OtherName />   <!-- optional, for individuals only -->   
  <DateOfBirth />   <!-- optional, for individuals only -->   


  <JobManagerUUID />  <!-- optional - UUID of staff member -->
  <TaxNumber /> 
  <CompanyNumber /> 
  <BusinessNumber /> 
  <BusinessStructure />   <!-- Name of Business Structure (as per Admin) -->
  <BalanceMonth />  <!-- e.g. Jan, 1, Feb, 2, Mar, 3 etc  -->
  <PrepareGST />   <!-- Yes or No -->
  <GSTRegistered />   <!-- Yes or No -->
  <GSTPeriod />  <!-- 1, 2, 6 -->
  <GSTBasis />  <!-- Invoice, Payment, Hybrid  -->
  <ProvisionalTaxBasis />  <!-- Standard Option, Estimate Option, Ratio Option  -->
  <ProvisionalTaxRatio /> 

  <!-- The following fields apply to NZ clients only -->
  <SignedTaxAuthority />  <!-- Yes or No -->
  <TaxAgent />  <!-- Name of Tax Agent (as per Admin) -->
  <AgencyStatus />  <!-- With EOT, Without EOT, Unlinked -->
  <ReturnType />  <!-- IR3, IR3NR, IR4, IR6, IR7, IR9, PTS  -->

  <!-- The following fields apply to AU clients only -->
  <PrepareActivityStatement />  <!-- Yes or No -->
  <PrepareTaxReturn />  <!-- Yes or No -->

</Client>

The response will include the detailed information of the client as per the GET get/[identifier] method

PUT update

Update a clients details

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/update

Example Message

<Client>
  <UUID>8add9c67-3893-40c1-8537-a900ad9e0b85</UUID>
  <Name>Bloggs Electrical Ltd</Name>
  <Email></Email>  <!-- optional -->   
  <Address></Address>  <!-- optional -->   
  <City></City>  <!-- optional -->   
  <Region></Region>  <!-- optional -->   
  <PostCode></PostCode>  <!-- optional -->   
  <Country></Country>  <!-- optional -->   
  <PostalAddress></PostalAddress>  <!-- optional -->   
  <PostalCity></PostalCity>  <!-- optional -->   
  <PostalRegion></PostalRegion>  <!-- optional -->   
  <PostalPostCode></PostalPostCode>  <!-- optional -->   
  <PostalCountry></PostalCountry>  <!-- optional -->   
  <Phone></Phone>  <!-- optional -->   
  <Fax></Fax>  <!-- optional -->   
  <WebSite></WebSite>  <!-- optional -->   
  <ReferralSource></ReferralSource>  <!-- optional -->   

  <AccountManagerUUID />  <!-- optional - UUID of staff member -->

  <BillingClientUUID /> <!-- optional UUID of billing client -->

  <!-- The following fields are only applicable if the Practice Management module is enabled -->

  <FirstName />   <!-- optional, for individuals only -->   
  <LastName />   <!-- optional, for individuals only -->   
  <OtherName />   <!-- optional, for individuals only -->   
  <DateOfBirth />   <!-- optional, for individuals only -->

  <JobManagerUUID />  <!-- optional - UUID of staff member -->

  <TaxNumber /> 
  <CompanyNumber /> 
  <BusinessNumber /> 
  <BusinessStructure />   <!-- Name of Business Structure (as per Admin) -->
  <BalanceMonth />  <!-- e.g. Jan, 1, Feb, 2, Mar, 3 etc  -->
  <PrepareGST />   <!-- Yes or No -->
  <GSTRegistered />   <!-- Yes or No -->
  <GSTPeriod />  <!-- 1, 2, 6 -->
  <GSTBasis />  <!-- Invoice, Payment, Hybrid  -->
  <ProvisionalTaxBasis />  <!-- Standard Option, Estimate Option, Ratio Option  -->
  <ProvisionalTaxRatio /> 

  <!-- The following fields apply to NZ clients only -->
  <SignedTaxAuthority />  <!-- Yes or No -->
  <TaxAgent />  <!-- Name of Tax Agent (as per Admin) -->
  <AgencyStatus />  <!-- With EOT, Without EOT, Unlinked -->
  <ReturnType />  <!-- IR3, IR3NR, IR4, IR6, IR7, IR9, PTS  -->

  <!-- The following fields apply to AU clients only -->
  <PrepareActivityStatement />  <!-- Yes or No -->
  <PrepareTaxReturn />  <!-- Yes or No -->
</Client>

The response will include the detailed information of the client as per the GET get/[identifier] method

PUT archive

Archive a client

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/archive

Example Message

<Client>
  <UUID>8add9c67-3893-40c1-8537-a900ad9e0b85</UUID>
</Client>

The response will include the detailed information of the client as per the GET get/[identifier] method

POST delete

Delete a client

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/delete

Example Message

<Client>
  <UUID>8add9c67-3893-40c1-8537-a900ad9e0b85</UUID>
</Client>

GET contact/[uuid]

Detailed information for a specific contact

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/contact/e873137a-7e07-49a0-8987-130e7418ad34

Example Response

<Response>
  <Status>OK</Status> 
  <Contact>
    <UUID>e873137a-7e07-49a0-8987-130e7418ad34</UUID>
    <IsPrimary>yes</IsPrimary>
    <Name>Wyett E Coyote</Name> 
    <Salutation /> 
    <Addressee /> 
    <Mobile /> 
    <Email /> 
    <Phone /> 
    <Position /> 
  </Contact>
</Response>

The response will include the detailed information of the contact as per GET contact/[uuid] method.

PUT contact/[uuid]

Update a contacts details

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/contact/e873137a-7e07-49a0-8987-130e7418ad34

Example Message

<Contact>
  <Name>Wyett E Coyote</Name>
  <IsPrimary>yes</IsPrimary> <!-- If multiple contacts defined, method will interpret last primary client as Primary -->
  <Salutation /> 
  <Addressee /> 
  <Mobile /> 
  <Email /> 
  <Phone /> 
  <Position /> 
</Contact>

POST contact

add a contact to a client

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/contact

Example Message

<Contact>
  <Client>
    <UUID>a19f59c6-9dce-47c7-9488-0f18b462c083</UUID>
  </Client>
  <Name>Wyett E Coyote</Name>
  <IsPrimary>yes</IsPrimary> <!-- If multiple contacts defined, method will interpret last primary client as Primary -->
  <Salutation /> 
  <Addressee /> 
  <Mobile /> 
  <Email /> 
  <Phone /> 
  <Position /> 
</Contact>

DELETE contact/[uuid]

delete a contact

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/contact/a19f59c6-9dce-47c7-9488-0f18b462c083

GET documents/[uuid]

Return a list of documents for a client

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/documents/0ffc6666-f75f-4d5c-a8ac-142ab62806b7

Example Message

<Documents>
  <Document>
    <Title>Document Title</Title>
    <Text />    <!-- optional -->
    <Folder>Correspondence</Folder>    <!-- optional -->
    <Date>20091023</Date>
    <CreatedBy>Jo Bloggs</CreatedBy>
    <URL>https://my.workflowmax.com/....... </URL>
  </Document>
</Documents>

POST document

Add a document to a client

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/document

Example Message

<Document>
  <ClientUUID>e873137a-7e07-49a0-8987-130e7418ad34</ClientUUID>
  <Title>Document Title</Title>
  <Text>The note relating to the document</Text>
  <Folder>Images</Folder>    <!-- optional -->
  <FileName>example.jpg</FileName>
  <Content>File content base 64 encoded</Content>
</Document>

POST addrelationship

Add a relationship between clients (Practice Manager only)

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/addrelationship

Example Message

<Relationship>
  <ClientUUID>e873137a-7e07-49a0-8987-130e7418ad34</ClientUUID>
  <RelatedClientUUID>03b35a92-bb2b-4b4e-91ad-3203abb8f992</RelatedClientUUID>
  <Type>Shareholder</Type>
  <!-- The following relationship types are supported: Director, Shareholder, Trustee, Beneficiary, Partner, Settlor, Associate, Secretary, Public Officer, Husband, Wife, Spouse, Parent Of, Child Of, Appointer, Member, Auditor, Owner. -->
  <NumberOfShares>1000</NumberOfShares>  <!-- only applicable when adding Shareholder or Owner relationship -->
  <Percentage>25</Percentange>  <!-- only applicable when adding Partnership relationship --> 
  <StartDate />  <!-- optional yyyy-MM-dd -->
  <EndDate />  <!-- optional yyyy-MM-dd -->
</Relationship>

POST updaterelationship

Update the relationship details between clients (Practice Manager only)

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/updaterelationship

Example Message

<Relationship>
  <UUID>e873137a-7e07-49a0-8987-130e7418ad34</UUID>
  <NumberOfShares>1000</NumberOfShares>  <!-- only applicable when Shareholder or Owner relationship -->
  <Percentage>30</Percentange>  <!-- only applicable when adding Partnership relationship --> 
  <StartDate />  <!-- optional yyyy-MM-dd -->
  <EndDate />  <!-- optional yyyy-MM-dd -->
</Relationship>

POST deleterelationship

Delete the relationship between clients (Practice Manager only)

EXAMPLE URL

https://api.xero.com/workflowmax/3.0/client.api/deleterelationship

Example Message

<Relationship>
  <UUID>e873137a-7e07-49a0-8987-130e7418ad34</UUID>
</Relationship>