Skip to main content

​
Overview

This recipe shows you how to update an existing card by passing its _id in the request body. The same endpoint is used for both creating and updating cards.

​
What you need

  • Your API key and board ID from Card Sources > API
  • The _id of the card you want to update
  • Update Mode set to Update if exists in Card Sources

​
Step 1: Confirm your Update Mode setting

Updating only works if the board’s Update Mode is set to Update if exists. If it is set to Always Create New, passing an _id will have no effect and a new card will be created instead. Check or change this in Card Sources > API on the board.

​
Step 2: Post the update

Pass the _id of the card alongside only the fields you want to change. Fields you omit are left as-is. 
const response = await fetch(
  "https://app.getaptly.com/api/aptlet/YOUR_BOARD_ID",
  {
    method: "POST",
    headers: {
      "x-token": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      _id: "JShpBxEFgRmZnivTf",
      Stage: "In Progress",
      Phone: "555-0199",
    }),
  }
);

const data = await response.json();
console.log("Updated card ID:", data._id);

​
Step 3: Confirm the update

Fetch the card to verify the fields were updated as expected. 
const response = await fetch(
  "https://app.getaptly.com/api/card/JShpBxEFgRmZnivTf",
  {
    headers: { "x-token": "YOUR_API_KEY" },
  }
);

const card = await response.json();
console.log(card.Stage); // "In Progress"

​
Things to watch out for

  • If the _id does not match any existing card and Update Mode is set to Update if exists, a new card will be created.
  • Only the fields you include in the payload are changed. All other fields on the card remain untouched.

​
Next steps