Skip to main content

​
Overview

This recipe shows you how to create a new card on a board and handle the response.

​
What you need

  • Your API key and board ID from Card Sources > API
  • The field names for your board (fetch the schema if you are unsure)

​
Step 1: Fetch the board schema

Field names must match the board schema exactly, including capitalisation. Fetch the schema to confirm the names before posting. 
const response = await fetch(
  "https://app.getaptly.com/api/schema/YOUR_BOARD_ID",
  {
    headers: { "x-token": "YOUR_API_KEY" },
  }
);

const schema = await response.json();
console.log(schema.fields.map((f) => f.name));
// ["Name", "Stage", "Email", "Phone", "Unit"]

​
Step 2: Post the card

Build a JSON object using the field names from the schema and POST it to the board endpoint. 
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({
      Name: "Jane Smith",
      Stage: "New Lead",
      Email: "jane@example.com",
      Phone: "555-0100",
      Unit: "4B",
    }),
  }
);

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

​
Step 3: Store the returned ID

The response contains the new card’s _id. Store this if you need to update or reference the card later. 
{ "_id": "JShpBxEFgRmZnivTf" }

​
Things to watch out for

  • If a field name does not match the schema, the value is silently ignored. No error is thrown.
  • If Create Fields is enabled in Card Sources, unknown keys will create new fields on the board instead of being dropped.
  • The Stage value must match an existing stage name on the board exactly.

​
Next steps