如何在Xero中上传下载图片及同步员工信息与头像？

Great question! Let's break this down step by step since Xero's payroll and contact systems are linked when it comes to employee avatars, and we'll cover general image upload/download workflows too.

Why the Payroll Employees API Isn't Enough #

Xero's Payroll Employees API (GET /payroll.xro/1.0/Employees/{ID} and POST /payroll.xro/1.0/Employees/) doesn't handle avatar data directly. That's because employee avatars are tied to the Contact entity's ContactPerson object, not the core payroll employee record itself.

How to Sync Employee Avatars #

You'll need to combine three Xero APIs to get and update avatars: Payroll Employees, Contacts, and Files. Here's the workflow:

1. Fetch the Employee's Associated Contact ID #

First, use your existing GET payroll employee endpoint. In the response, look for the ContactID field—this is the link between the payroll employee and their corresponding contact record.

2. Retrieve the Employee's Avatar #

Use the Contacts API to pull the linked contact details:

GET https://api.xero.com/api.xro/2.0/Contacts/{ContactID}

In the response, navigate to the ContactPersons array. Find the entry matching your employee (match via FirstName/LastName or EmployeeID), and you'll see a ProfilePictureURL field—this is the direct URL to download the avatar image.

3. Update the Employee's Avatar #

Updating requires two key steps:

• Step 1: Upload the image to Xero's Files API
  Send a multipart/form-data POST request to upload your image:

  POST https://api.xero.com/files.xro/1.0/Files
  

  Include these form fields:

  • Name: The filename of your image (e.g., john-doe-avatar.png)
  • MimeType: The image type (e.g., image/png or image/jpeg)
  • File: The actual image file content
    Save the FileID returned in the response—you'll need this for the next step.

• Step 2: Link the uploaded image to the employee's contact
  Send a PUT request to update the contact record:

  PUT https://api.xero.com/api.xro/2.0/Contacts/{ContactID}
  

  In the request body, target the correct ContactPerson entry and set its ProfilePictureID to the FileID from the upload step:

  {
    "ContactPersons": [
      {
        "ContactPersonID": "{ContactPersonID}",
        "ProfilePictureID": "{FileID}"
      }
    ]
  }
  

For any image uploads or downloads outside of avatars, use Xero's Files API:

Uploading Images #

Use the same POST /files.xro/1.0/Files endpoint mentioned above. Ensure your app has the files scope permission enabled in Xero's developer portal.

Downloading Images #

You have two reliable options:

• Use the DownloadURL returned in the Files API upload response (note: this URL has a short expiration window, so you'll need to re-fetch it if it expires)
• Send a GET request to fetch the file content directly:

  GET https://api.xero.com/files.xro/1.0/Files/{FileID}/Content
  

• Double-check your app's scopes: you'll need payroll.employees, contacts, and files permissions to execute all these steps without errors.
• When updating ContactPersons, you only need to include the fields you're modifying (like ProfilePictureID) along with the ContactPersonID to identify the correct entry—no need to send the full contact person object.

内容的提问来源于stack exchange，提问作者Gnana