younifyd
Menu

Update Or Create Contacts

Updates or creates one or more contacts in a Xero organisation

POST/Contacts

Use it in a workflow

  1. Add a step and choose the Xero connector.
  2. Pick the Update Or Create Contacts action (under Xero).
  3. Fill in the fields below, then reference the result from later steps as {{updateOrCreateContacts.response.data}}.

Request

Query parameters

summarizeErrorsboolean

If false return 200 OK and mix of successfully created objects and any with validation errors

Default false

Headers

xero-tenant-idstringrequired

Xero identifier for Tenant

Idempotency-Keystring

This allows you to safely retry requests without the risk of duplicate processing. 128 character max.

Request body

Enter the body as JSON in the step's Body field.

paginationobject
pageinteger
pageSizeinteger
pageCountinteger
itemCountinteger
Warningsarray<object>

Displays array of warning messages from the API

Messagestring

Validation error message

Contactsarray<object>
ContactIDstring (uuid)

Xero identifier

MergedToContactIDstring (uuid)

ID for the destination of a merged contact. Only returned when using paging or when fetching a contact by ContactId or ContactNumber.

ContactNumberstring

This can be updated via the API only i.e. This field is read only on the Xero contact screen, used to identify contacts in external systems (max length = 50). If the Contact Number is used, this is displayed as Contact Code in the Contacts UI in Xero.

AccountNumberstring

A user defined account number. This can be updated via the API and the Xero UI (max length = 50)

ContactStatusstring

Current status of a contact – see contact status types

One ofACTIVEARCHIVEDGDPRREQUEST

Namestring

Full name of contact/organisation (max length = 255)

FirstNamestring

First name of contact person (max length = 255)

LastNamestring

Last name of contact person (max length = 255)

CompanyNumberstring

Company registration number (max length = 50)

EmailAddressstring

Email address of contact person (umlauts not supported) (max length = 255)

ContactPersonsarray<object>4 fields

See contact persons

BankAccountDetailsstring

Bank account number of contact

TaxNumberstring

Tax number of contact – this is also known as the ABN (Australia), GST Number (New Zealand), VAT Number (UK) or Tax ID Number (US and global) in the Xero UI depending on which regionalized version of Xero you are using (max length = 50)

TaxNumberTypestring

Identifier of the regional type of tax number, such as US, UK, or other regional tax identifiers

One ofSSNEINITINATIN

AccountsReceivableTaxTypestring

The tax type from TaxRates

AccountsPayableTaxTypestring

The tax type from TaxRates

Addressesarray<object>10 fields

Store certain address types for a contact – see address types

Phonesarray<object>4 fields

Store certain phone types for a contact – see phone types

IsSupplierboolean

true or false – Boolean that describes if a contact that has any AP invoices entered against them. Cannot be set via PUT or POST – it is automatically set when an accounts payable invoice is generated against this contact.

IsCustomerboolean

true or false – Boolean that describes if a contact has any AR invoices entered against them. Cannot be set via PUT or POST – it is automatically set when an accounts receivable invoice is generated against this contact.

SalesDefaultLineAmountTypestring

The default sales line amount type for a contact. Only available when summaryOnly parameter or paging is used, or when fetch by ContactId or ContactNumber.

One ofINCLUSIVEEXCLUSIVENONE

PurchasesDefaultLineAmountTypestring

The default purchases line amount type for a contact Only available when summaryOnly parameter or paging is used, or when fetch by ContactId or ContactNumber.

One ofINCLUSIVEEXCLUSIVENONE

DefaultCurrencystring

3 letter alpha code for the currency – see list of currency codes

One ofAEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBYRBZDCADCDFCHFCLFCLPCNYCOPCRCCUCCUPCVECZKDJFDKK

XeroNetworkKeystring

Store XeroNetworkKey for contacts.

SalesDefaultAccountCodestring

The default sales account code for contacts

PurchasesDefaultAccountCodestring

The default purchases account code for contacts

SalesTrackingCategoriesarray<object>2 fields

The default sales tracking categories for contacts

PurchasesTrackingCategoriesarray<object>2 fields

The default purchases tracking categories for contacts

TrackingCategoryNamestring

The name of the Tracking Category assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories

TrackingCategoryOptionstring

The name of the Tracking Option assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories

PaymentTermsobject2 fields
UpdatedDateUTCstring

UTC timestamp of last update to contact

ContactGroupsarray<object>4 fields

Displays which contact groups a contact is included in

Websitestring

Website address for contact (read only)

BrandingThemeobject6 fields
BatchPaymentsobject5 fields

Bank details for use on a batch payment stored with each contact

Discountnumber (double)

The default discount rate for the contact (read only)

Balancesobject2 fields

The raw AccountsReceivable(sales invoices) and AccountsPayable(bills) outstanding and overdue amounts, not converted to base currency (read only)

Attachmentsarray<object>6 fields

Displays array of attachments from the API

HasAttachmentsboolean

A boolean to indicate if a contact has an attachment

Default "false"

json
{
  "pagination": {
    "page": 0,
    "pageSize": 0,
    "pageCount": 0,
    "itemCount": 0
  },
  "Warnings": [
    {
      "Message": "string"
    }
  ],
  "Contacts": [
    {
      "ContactID": "00000000-0000-0000-0000-000000000000",
      "MergedToContactID": "00000000-0000-0000-0000-000000000000",
      "ContactNumber": "string",
      "AccountNumber": "string",
      "ContactStatus": "ACTIVE",
      "Name": "string",
      "FirstName": "string",
      "LastName": "string",
      "CompanyNumber": "string",
      "EmailAddress": "string",
      "ContactPersons": [
        {
          "FirstName": "string",
          "LastName": "string",
          "EmailAddress": "string",
          "IncludeInEmails": false
        }
      ],
      "BankAccountDetails": "string"
    }
  ]
}

Response

Returns 200 with an object. Read it in later steps with {{updateOrCreateContacts.response.data.<field>}}.

paginationobject
pageinteger
pageSizeinteger
pageCountinteger
itemCountinteger
Warningsarray<object>

Displays array of warning messages from the API

Messagestring

Validation error message

Contactsarray<object>
ContactIDstring (uuid)

Xero identifier

MergedToContactIDstring (uuid)

ID for the destination of a merged contact. Only returned when using paging or when fetching a contact by ContactId or ContactNumber.

ContactNumberstring

This can be updated via the API only i.e. This field is read only on the Xero contact screen, used to identify contacts in external systems (max length = 50). If the Contact Number is used, this is displayed as Contact Code in the Contacts UI in Xero.

AccountNumberstring

A user defined account number. This can be updated via the API and the Xero UI (max length = 50)

ContactStatusstring

Current status of a contact – see contact status types

One ofACTIVEARCHIVEDGDPRREQUEST

Namestring

Full name of contact/organisation (max length = 255)

FirstNamestring

First name of contact person (max length = 255)

LastNamestring

Last name of contact person (max length = 255)

CompanyNumberstring

Company registration number (max length = 50)

EmailAddressstring

Email address of contact person (umlauts not supported) (max length = 255)

ContactPersonsarray<object>4 fields

See contact persons

BankAccountDetailsstring

Bank account number of contact

TaxNumberstring

Tax number of contact – this is also known as the ABN (Australia), GST Number (New Zealand), VAT Number (UK) or Tax ID Number (US and global) in the Xero UI depending on which regionalized version of Xero you are using (max length = 50)

TaxNumberTypestring

Identifier of the regional type of tax number, such as US, UK, or other regional tax identifiers

One ofSSNEINITINATIN

AccountsReceivableTaxTypestring

The tax type from TaxRates

AccountsPayableTaxTypestring

The tax type from TaxRates

Addressesarray<object>10 fields

Store certain address types for a contact – see address types

Phonesarray<object>4 fields

Store certain phone types for a contact – see phone types

IsSupplierboolean

true or false – Boolean that describes if a contact that has any AP invoices entered against them. Cannot be set via PUT or POST – it is automatically set when an accounts payable invoice is generated against this contact.

IsCustomerboolean

true or false – Boolean that describes if a contact has any AR invoices entered against them. Cannot be set via PUT or POST – it is automatically set when an accounts receivable invoice is generated against this contact.

SalesDefaultLineAmountTypestring

The default sales line amount type for a contact. Only available when summaryOnly parameter or paging is used, or when fetch by ContactId or ContactNumber.

One ofINCLUSIVEEXCLUSIVENONE

PurchasesDefaultLineAmountTypestring

The default purchases line amount type for a contact Only available when summaryOnly parameter or paging is used, or when fetch by ContactId or ContactNumber.

One ofINCLUSIVEEXCLUSIVENONE

DefaultCurrencystring

3 letter alpha code for the currency – see list of currency codes

One ofAEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBYRBZDCADCDFCHFCLFCLPCNYCOPCRCCUCCUPCVECZKDJFDKK

XeroNetworkKeystring

Store XeroNetworkKey for contacts.

SalesDefaultAccountCodestring

The default sales account code for contacts

PurchasesDefaultAccountCodestring

The default purchases account code for contacts

SalesTrackingCategoriesarray<object>2 fields

The default sales tracking categories for contacts

PurchasesTrackingCategoriesarray<object>2 fields

The default purchases tracking categories for contacts

TrackingCategoryNamestring

The name of the Tracking Category assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories

TrackingCategoryOptionstring

The name of the Tracking Option assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories

PaymentTermsobject2 fields
UpdatedDateUTCstring

UTC timestamp of last update to contact

ContactGroupsarray<object>4 fields

Displays which contact groups a contact is included in

Websitestring

Website address for contact (read only)

BrandingThemeobject6 fields
BatchPaymentsobject5 fields

Bank details for use on a batch payment stored with each contact

Discountnumber (double)

The default discount rate for the contact (read only)

Balancesobject2 fields

The raw AccountsReceivable(sales invoices) and AccountsPayable(bills) outstanding and overdue amounts, not converted to base currency (read only)

Attachmentsarray<object>6 fields

Displays array of attachments from the API

HasAttachmentsboolean

A boolean to indicate if a contact has an attachment

Default "false"

json
{
  "pagination": {
    "page": 0,
    "pageSize": 0,
    "pageCount": 0,
    "itemCount": 0
  },
  "Warnings": [
    {
      "Message": "string"
    }
  ],
  "Contacts": [
    {
      "ContactID": "00000000-0000-0000-0000-000000000000",
      "MergedToContactID": "00000000-0000-0000-0000-000000000000",
      "ContactNumber": "string",
      "AccountNumber": "string",
      "ContactStatus": "ACTIVE",
      "Name": "string",
      "FirstName": "string",
      "LastName": "string",
      "CompanyNumber": "string",
      "EmailAddress": "string",
      "ContactPersons": [
        {
          "FirstName": "string",
          "LastName": "string",
          "EmailAddress": "string",
          "IncludeInEmails": false
        }
      ],
      "BankAccountDetails": "string"
    }
  ]
}

Need more? See the Xero guide for connection setup and behaviour shared by every action.