Update a Segment via the API

Change the name, description, rules or time zone of an AhaSend segment. New rules or a new time zone make AhaSend find the members of the segment again.

PUT /v2/accounts/{account_id}/segments/{segment_id}

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()

  segmentID := uuid.MustParse("11111111-1111-4111-8111-111111111111")

  // Only the fields you set change. A new name or description keeps the
  // members; a new definition or time zone builds them again.
  response, _, err := client.SegmentsAPI.UpdateSegment(ctx, accountID, segmentID, requests.UpdateSegmentRequest{
    Name:        ahasend.String("Engaged customers"),
    Description: ahasend.String("Opened a campaign recently"),
  })
  if err != nil {
    log.Fatalf("Error updating segment: %v", err)
  }
  fmt.Printf("Updated segment %s (%s)\n", response.Name, response.State)
}

200

{
  "object": "segment",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "description": "<string>",
  "definition": {
    "schema_version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "attributes.country",
        "op": "equal",
        "value": "DE"
      },
      {
        "field": "created_at",
        "op": "after",
        "value": "30 days ago"
      },
      {
        "field": "list",
        "op": "in",
        "value": "6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b"
      },
      {
        "match": "any",
        "conditions": [
          {
            "field": "campaign",
            "op": "opened",
            "value": "9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b"
          },
          {
            "field": "any_campaign",
            "op": "clicked",
            "value": "14 days ago"
          },
          {
            "field": "campaign_count",
            "op": "opened_at_least",
            "value": {
              "count": 3,
              "since": "90 days ago"
            }
          }
        ]
      }
    ]
  },
  "timezone": "<string>",
  "state": "building",
  "failure_reason": "<string>",
  "member_count": 1,
  "last_evaluated_at": "2023-11-07T05:31:56Z"
}

The AhaSend API changes one segment. Access requires segments:write.

Fields:

• A field that you leave out or send as null does not change.
• name and description follow the same rules as in Create Segment.
• definition replaces the stored rules as a whole. See Definitions.
• timezone is an IANA time zone. An empty string stores UTC.
• A field that you cannot write is refused with 400, and the message names it.

Members:

• A change of definition or timezone builds the members again. The segment is building until that ends, and a campaign that uses it cannot be sent until then.
• A change of only name or description keeps the members and the state.
• Any update of a failed segment, {} included, builds it again.

See States.

A segment that is being changed, for example by an update of its members, answers 409 with The segment is being updated. Try again in a minute. Nothing was changed, so send the request again later.

Related Guides

• API authentication, Permission scopes, Get Segment.
• Segments 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.

Path Parameters

account_id · string<uuid> · required

Account ID

segment_id · string<uuid> · required

Segment ID

Body

application/json

A partial segment update. An omitted or null property leaves the stored value unchanged. A change of definition or timezone builds the segment's members again, and it is building until that ends; a change of only name or description leaves its members and its state as they are. A property that is not writable is rejected with 400 naming it.

name · string | null

Trimmed and bounded exactly as on create.

Required string length: 1 - 255

description · string | null

Trimmed and bounded exactly as on create.

Maximum string length: 1000

definition · object | null

The new rules, which replace the stored ones as a whole.

Show child attributes

Example:

{
  "schema_version": 1,
  "match": "all",
  "conditions": [
    {
      "field": "attributes.country",
      "op": "equal",
      "value": "DE"
    },
    {
      "field": "created_at",
      "op": "after",
      "value": "30 days ago"
    },
    {
      "field": "list",
      "op": "in",
      "value": "6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b"
    },
    {
      "match": "any",
      "conditions": [
        {
          "field": "campaign",
          "op": "opened",
          "value": "9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b"
        },
        {
          "field": "any_campaign",
          "op": "clicked",
          "value": "14 days ago"
        },
        {
          "field": "campaign_count",
          "op": "opened_at_least",
          "value": { "count": 3, "since": "90 days ago" }
        }
      ]
    }
  ]
}

timezone · string | null

The IANA time zone, as on create. Null and omission keep the stored zone; an empty string stores UTC.

Response

200

application/json

Segment updated

A saved set of rules over the account's contacts, and the contacts that match them.

object · enum<string> · required

Object type identifier

Available options: segment

id · string<uuid> · required

Unique identifier for the segment

created_at · string<date-time> · required

When the segment was created

updated_at · string<date-time> · required

When the segment was last saved

name · string · required

Segment name; names are not unique within an account

description · string · required

Free-text description; empty when none was given

definition · object · required

The rules of a segment. The root group holds conditions and groups; a group holds conditions only, so groups nest one level deep. A definition has at most 50 conditions in all, and at most 5 of them are campaign, any_campaign or campaign_count conditions. An unknown key, or a schema_version other than 1, is refused. A refused definition is answered with 400 and a message that names each problem by its path, such as conditions[3].value.

Show child attributes

Example:

{
  "schema_version": 1,
  "match": "all",
  "conditions": [
    {
      "field": "attributes.country",
      "op": "equal",
      "value": "DE"
    },
    {
      "field": "created_at",
      "op": "after",
      "value": "30 days ago"
    },
    {
      "field": "list",
      "op": "in",
      "value": "6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b"
    },
    {
      "match": "any",
      "conditions": [
        {
          "field": "campaign",
          "op": "opened",
          "value": "9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b"
        },
        {
          "field": "any_campaign",
          "op": "clicked",
          "value": "14 days ago"
        },
        {
          "field": "campaign_count",
          "op": "opened_at_least",
          "value": { "count": 3, "since": "90 days ago" }
        }
      ]
    }
  ]
}

timezone · string · required

The IANA time zone that relative times and days in the definition are read in

state · enum<string> · required

• building: the members are being found for the current definition. A campaign that uses the segment cannot be sent until it is ready.
• ready: the members follow the current definition.
• failed: the members could not be found; failure_reason says why. Any update of the segment, {} included, builds it again.

Available options: building, ready, failed

failure_reason · string | null · required

Why the segment failed. Null unless state is failed.

member_count · integer · required

The contacts that match the rules, whatever their consent. A campaign reaches only those of them who may get marketing email; Get Segment counts them as marketable_count.

Required range: x >= 0

last_evaluated_at · string<date-time> | null · required

When the members were last checked against the whole account. Null until the first build ends.