Country Custom Field

Create country selection fields with ISO country code validation

Country custom fields allow you to store and manage country information for records. The field supports both country names and ISO Alpha-2 country codes.

Important: Country validation and conversion behavior differs significantly between mutations:

createTodo: Automatically validates and converts country names to ISO codes
setTodoCustomField: Accepts any value without validation

Basic Example

Create a simple country field:

mutation CreateCountryField {
  createCustomField(input: {
    name: "Country of Origin"
    type: COUNTRY
    projectId: "proj_123"
  }) {
    id
    name
    type
  }
}

Advanced Example

Create a country field with description:

mutation CreateDetailedCountryField {
  createCustomField(input: {
    name: "Customer Location"
    type: COUNTRY
    projectId: "proj_123"
    description: "Primary country where the customer is located"
    isActive: true
  }) {
    id
    name
    type
    description
    isActive
  }
}

Input Parameters

CreateCustomFieldInput

Parameter	Type	Required	Description
`name`	String!	✅ Yes	Display name of the country field
`type`	CustomFieldType!	✅ Yes	Must be `COUNTRY`
`description`	String	No	Help text shown to users

Note: The projectId is not passed in the input but is determined by the GraphQL context (typically from request headers or authentication).

Setting Country Values

Country fields store data in two database fields:

countryCodes: Stores ISO Alpha-2 country codes as a comma-separated string in the database (returned as array via API)
text: Stores display text or country names as a string

Understanding the Parameters

The setTodoCustomField mutation accepts two optional parameters for country fields:

Parameter	Type	Required	Description	What it does
`todoId`	String!	✅ Yes	ID of the record to update	-
`customFieldId`	String!	✅ Yes	ID of the country custom field	-
`countryCodes`	[String!]	No	Array of ISO Alpha-2 country codes	Stored in the `countryCodes` field
`text`	String	No	Display text or country names	Stored in the `text` field

Important:

In setTodoCustomField: Both parameters are optional and stored independently
In createTodo: The system automatically sets both fields based on your input (you cannot control them independently)

Option 1: Using Only Country Codes

Store validated ISO codes without display text:

mutation SetCountryByCode {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    countryCodes: ["US"]
  })
}

Result: countryCodes = ["US"], text = null

Option 2: Using Only Text

Store display text without validated codes:

mutation SetCountryByText {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    text: "United States"
  })
}

Result: countryCodes = null, text = "United States"

Note: When using setTodoCustomField, no validation occurs regardless of which parameter you use. The values are stored exactly as provided.

Option 3: Using Both (Recommended)

Store both validated codes and display text:

mutation SetCountryComplete {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    countryCodes: ["US"]
    text: "United States"
  })
}

Result: countryCodes = ["US"], text = "United States"

Multiple Countries

Store multiple countries using arrays:

mutation SetMultipleCountries {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    countryCodes: ["US", "CA", "MX"]
    text: "North American Markets"  # Can be any descriptive text
  })
}

Creating Records with Country Values

When creating records, the createTodo mutation automatically validates and converts country values. This is the only mutation that performs country validation:

mutation CreateRecordWithCountry {
  createTodo(input: {
    title: "International Client"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "country_field_id"
      value: "France"  # Can use country name or code
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      text
      countryCodes
    }
  }
}

Accepted Input Formats

Input Type	Example	Result
Country Name	`"United States"`	Stored as `US`
ISO Alpha-2 Code	`"GB"`	Stored as `GB`
Multiple (comma-separated)	`"US, CA"`	Not supported - treated as single invalid value
Mixed format	`"United States, CA"`	Not supported - treated as single invalid value

Response Fields

TodoCustomField Response

Field	Type	Description
`id`	String!	Unique identifier for the field value
`customField`	CustomField!	The custom field definition
`text`	String	Display text (country names)
`countryCodes`	[String!]	Array of ISO Alpha-2 country codes
`todo`	Todo!	The record this value belongs to
`createdAt`	DateTime!	When the value was created
`updatedAt`	DateTime!	When the value was last modified

Country Standards

Blue uses the ISO 3166-1 Alpha-2 standard for country codes:

Two-letter country codes (e.g., US, GB, FR, DE)
Validation using the i18n-iso-countries library only occurs in createTodo
Supports all officially recognized countries

Example Country Codes

Country	ISO Code
United States	`US`
United Kingdom	`GB`
Canada	`CA`
Germany	`DE`
France	`FR`
Japan	`JP`
Australia	`AU`
Brazil	`BR`

For the complete official list of ISO 3166-1 alpha-2 country codes, visit the ISO Online Browsing Platform.

Validation

Validation only occurs in the createTodo mutation:

Valid ISO Code: Accepts any valid ISO Alpha-2 code
Country Name: Automatically converts recognized country names to codes
Invalid Input: Throws CustomFieldValueParseError for unrecognized values

Note: The setTodoCustomField mutation performs NO validation and accepts any string value.

Error Example

{
  "errors": [{
    "message": "Invalid country value.",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Integration Features

Lookup Fields

Country fields can be referenced by LOOKUP custom fields, allowing you to pull country data from related records.

Automations

Use country values in automation conditions:

Filter actions by specific countries
Send notifications based on country
Route tasks based on geographic regions

Forms

Country fields in forms automatically validate user input and convert country names to codes.

Required Permissions

Action	Required Permission
Create country field	Project `OWNER` or `ADMIN` role
Update country field	Project `OWNER` or `ADMIN` role
Set country value	Standard record edit permissions
View country value	Standard record view permissions

Error Responses

Invalid Country Value

{
  "errors": [{
    "message": "Invalid country value provided",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Field Type Mismatch

{
  "errors": [{
    "message": "Field type mismatch: expected COUNTRY",
    "extensions": {
      "code": "INVALID_FIELD_TYPE"
    }
  }]
}

Best Practices

Input Handling

Use createTodo for automatic validation and conversion
Use setTodoCustomField carefully as it bypasses validation
Consider validating inputs in your application before using setTodoCustomField
Display full country names in UI for clarity

Data Quality

Validate country inputs at entry point
Use consistent formats across your system
Consider regional groupings for reporting

Multiple Countries

Use array support in setTodoCustomField for multiple countries
Multiple countries in createTodo are not supported via the value field
Store country codes as array in setTodoCustomField for proper handling

Common Use Cases

Customer Management
- Customer headquarters location
- Shipping destinations
- Tax jurisdictions
Project Tracking
- Project location
- Team member locations
- Market targets
Compliance & Legal
- Regulatory jurisdictions
- Data residency requirements
- Export controls
Sales & Marketing
- Territory assignments
- Market segmentation
- Campaign targeting

Limitations

Only supports ISO 3166-1 Alpha-2 codes (2-letter codes)
No built-in support for country subdivisions (states/provinces)
No automatic country flag icons (text-based only)
Cannot validate historical country codes
No built-in region or continent grouping
Validation only works in createTodo, not in setTodoCustomField
Multiple countries not supported in createTodo value field
Country codes stored as comma-separated string, not true array

Custom Fields Overview - General custom field concepts
Lookup Fields - Reference country data from other records
Forms API - Include country fields in custom forms

Basic Example

Advanced Example

Input Parameters

CreateCustomFieldInput

Setting Country Values

Understanding the Parameters

Option 1: Using Only Country Codes

Option 2: Using Only Text

Option 3: Using Both (Recommended)

Multiple Countries

Creating Records with Country Values

Accepted Input Formats

Response Fields

TodoCustomField Response

Country Standards

Example Country Codes

Validation

Error Example

Integration Features

Lookup Fields

Automations

Forms

Required Permissions

Error Responses

Invalid Country Value

Field Type Mismatch

Best Practices

Input Handling

Data Quality

Multiple Countries

Common Use Cases

Limitations

AI Assistant

How can I help you?

Basic Example

Advanced Example

Input Parameters

CreateCustomFieldInput

Setting Country Values

Understanding the Parameters

Option 1: Using Only Country Codes

Option 2: Using Only Text

Option 3: Using Both (Recommended)

Multiple Countries

Creating Records with Country Values

Accepted Input Formats

Response Fields

TodoCustomField Response

Country Standards

Example Country Codes

Validation

Error Example

Integration Features

Lookup Fields

Automations

Forms

Required Permissions

Error Responses

Invalid Country Value

Field Type Mismatch

Best Practices

Input Handling

Data Quality

Multiple Countries

Common Use Cases

Limitations

Related Resources

AI Assistant

How can I help you?