Create or Update Contacts in a Batch via the API

Create or update up to 1,000 AhaSend contacts in one request, matched by email address. Each gets its own result, so one bad record does not stop the rest.

POST /v2/accounts/{account_id}/contacts/batch

AhaSend Go SDK

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  "github.com/AhaSend/ahasend-go"
  "github.com/AhaSend/ahasend-go/api"
  "github.com/AhaSend/ahasend-go/models/requests"
  "github.com/google/uuid"
)

func main() {
  client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
  accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
  ctx := context.Background()

  // The SDK sends a fresh Idempotency-Key with this POST and reuses it on
  // its own retries, so a retried request is not applied twice.
  response, _, err := client.ContactsAPI.BatchUpsertContacts(ctx, accountID, requests.BatchUpsertContactsRequest{
    Data: []requests.BatchUpsertContactInput{
      {Email: "[e-mail]"},
      {Email: "[e-mail]", Unsubscribed: ahasend.Bool(true)},
    },
  })
  if err != nil {
    log.Fatalf("Error upserting contacts: %v", err)
  }
  // Each item succeeds or fails on its own.
  fmt.Printf("created=%d updated=%d failed=%d\n", response.Created, response.Updated, response.Failed)
  for _, result := range response.Data {
    if result.Reason != "" {
      fmt.Printf("%s: %s (%s)\n", result.Email, result.Outcome, result.Reason)
    }
  }
}

200

{
  "object": "list",
  "created": 1,
  "updated": 1,
  "failed": 1,
  "data": [
    {
      "position": 1,
      "email": "<string>",
      "outcome": "created",
      "contact": {
        "object": "contact",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "email": "[e-mail]",
        "first_name": "<string>",
        "last_name": "<string>",
        "status": "enabled",
        "status_reason": "<string>",
        "unsubscribed": true,
        "unsubscribed_at": "2023-11-07T05:31:56Z",
        "attributes": {},
        "validation_status": "unvalidated",
        "last_validated_at": "2023-11-07T05:31:56Z"
      },
      "reason": "<string>"
    }
  ]
}

The AhaSend API creates or updates 1 to 1,000 contacts in one request, and answers when the work is done. Access requires contacts:write.

Matching and fields:

• Each entry needs email. The API trims it and changes it to lowercase, then updates the contact with that address, or creates one.
• On an update, a field that you leave out or send as null does not change. On a create, such a field gets the same default as in Create Contact.
• attributes is merged into the stored attributes, and a null value removes that key. See Attributes.

Results:

• data gives one result for each entry, in the order of the request. position is the index of the entry. outcome is created, updated or failed, and a failed entry has a reason.
• created, updated and failed count the results.
• An entry that fails does not stop the other entries.
• When two or more entries have the same email address after it is trimmed and changed to lowercase, all of them fail.
• An empty data array, more than 1,000 entries or a malformed body is refused with 400 for the whole request.

The contacts are not added to a list. To add them, use Batch Add List Contacts.

Pacing: 1,000 is a limit, not a target. Measure how long a batch takes with real data. Send the next batch only after the previous response arrives, and send smaller batches or wait longer when the time grows. After a 429, wait before you continue. The API does not promise a fixed throughput. See API rate limits.

This operation accepts an Idempotency-Key header. The changes and the stored response are saved together. A retry with the same key replays the 200 or the 400 for 24 hours. See Idempotency.

Related Guides

• API authentication, Permission scopes, Idempotency.
• Contacts API overview, API errors, API rate limits.

Authorizations

Authorization · string · header · required

API key for authentication. Non-empty Security Requirement values are AhaSend API-key roles. Roles listed within one requirement object are jointly required; separate requirement objects are alternatives.

Headers

Idempotency-Key · string

Optional idempotency key for safe request retries. Must be a unique string for each logical request. An identical request with a completed stored outcome returns the original status and body. An in-progress execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again. Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time secret_key, so successful encrypted replay responses for those operations expire after 5 minutes.

Maximum string length: 255

Path Parameters

account_id · string<uuid> · required

Body

application/json

data · object[] · required

Required array length: 1 - 1000 elements

Show child attributes

Response

200

application/json

Ordered per-contact outcomes

object · enum<string> · required

Available options: list

created · integer · required

Required range: x >= 0

updated · integer · required

Required range: x >= 0

failed · integer · required

Required range: x >= 0

data · object[] · required

Show child attributes