Stay organized with collections
Save and categorize content based on your preferences.
The ExternalIdentifier entity lets feed creators associate arbitrary sets of
source-value pairs with certain objects. ExternalIdentifier is a often
jurisdiction's code in an external system that's used to associate a
jurisdiciton with objects such as candidates, offices, or geopolitical units.
The Type field of an ExternalIdentifier entity is used to describe the
source of the identifier, not the object being identified. For example, two of
the built-in types are fips, an abbreviation of "Federal Information
Processing Standard" code, and state. Even though FIPS two-digit codes can be
used to describe states, the intended Type value for this situation is fips
and not state. That's because fips describes the source of the identifier.
External identifiers are used throughout the feed for the following purposes:
Provide a canonical identifier from an external resource, such as Open Civic
Data Identifiers or FIPS code.
Provide additional attributes that aren't native to the NIST CDF schema.
When used to provide additional data or context for an object, external
identifiers need to use a Type of other. They also include an OtherType
and a Value that both depend on the type of data that's provided. For an
example of how data can be provided in this manner, see
Office.
Attributes
The following table describes the attributes for ExternalIdentifier:
Attribute
Required?
Type
Description
label
Optional
string
An informative label. For use as needed.
Elements
The following table shows the elements for ExternalIdentifier:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-08-21 UTC."],[[["\u003cp\u003eThe \u003ccode\u003eExternalIdentifier\u003c/code\u003e entity allows associating arbitrary source-value pairs with objects, often used for jurisdiction codes in external systems.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eType\u003c/code\u003e field describes the source of the identifier (e.g., 'fips', 'state'), not the object being identified.\u003c/p\u003e\n"],["\u003cp\u003eExternal identifiers can provide stable identifiers, canonical identifiers from external resources, or additional attributes.\u003c/p\u003e\n"],["\u003cp\u003eWhen providing extra data or context, external identifiers use a \u003ccode\u003eType\u003c/code\u003e of \u003ccode\u003eother\u003c/code\u003e, accompanied by \u003ccode\u003eOtherType\u003c/code\u003e and \u003ccode\u003eValue\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eMultiple \u003ccode\u003eExternalIdentifier\u003c/code\u003e entities can be used within \u003ccode\u003eExternalIdentifiers\u003c/code\u003e to associate an object with multiple codes.\u003c/p\u003e\n"]]],[],null,["# ExternalIdentifier\n\nThe `ExternalIdentifier` entity lets feed creators associate arbitrary sets of\nsource-value pairs with certain objects. `ExternalIdentifier` is a often\njurisdiction's code in an external system that's used to associate a\njurisdiciton with objects such as candidates, offices, or geopolitical units.\n| **Note:** This entity is the same for all feed types.\n\nThe `Type` field of an `ExternalIdentifier` entity is used to describe the\n*source* of the identifier, not the object being identified. For example, two of\nthe built-in types are `fips`, an abbreviation of \"Federal Information\nProcessing Standard\" code, and `state`. Even though FIPS two-digit codes can be\nused to describe states, the intended `Type` value for this situation is `fips`\nand not `state`. That's because `fips` describes the source of the identifier.\n\nExternal identifiers are used throughout the feed for the following purposes:\n\n- Provide a [stable identifier](/civics-data/guides/stable-identifiers).\n- Provide a canonical identifier from an external resource, such as Open Civic Data Identifiers or FIPS code.\n- Provide additional attributes that aren't native to the NIST CDF schema.\n\nWhen used to provide additional data or context for an object, external\nidentifiers need to use a `Type` of `other`. They also include an `OtherType`\nand a `Value` that both depend on the type of data that's provided. For an\nexample of how data can be provided in this manner, see\n[`Office`](/civics-data/reference/office?feed=pre-election#additional-types-external-identifiers).\n| **Note:** The plural `ExternalIdentifiers` is a [collection](/civics-data/reference/collections) that wraps one or more `ExternalIdentifier` entities. Multiple occurrences of the `ExternalIdentifier` sub-entity can be used to associate a jurisdiction with multiple codes.\n\nAttributes\n----------\n\nThe following table describes the attributes for `ExternalIdentifier`:\n\n| Attribute | Required? | Type | Description |\n|-----------|-----------|----------|------------------------------------------|\n| `label` | Optional | `string` | An informative label. For use as needed. |\n\nElements\n--------\n\nThe following table shows the elements for `ExternalIdentifier`:\n\n| Element | Multiplicity | Type | Description |\n|-------------|--------------|------------------------------------------------------------|-----------------------------------------------------|\n| `Type` | 1 | [`IdentifierType`](/civics-data/reference/identifier-type) | Provides an identifier type. |\n| `OtherType` | 0 or 1 | `string` | Used when the value of `IdentifierType` is `other`. |\n| `Value` | 1 | `string` | The identifier used by the jurisdiction. |\n\nExamples\n--------\n\n### XML\n\n```xml\n \u003cExternalIdentifiers\u003e\n \u003cExternalIdentifier\u003e\n \u003cType\u003eother\u003c/Type\u003e\n \u003cOtherType\u003estable\u003c/OtherType\u003e\n \u003cValue\u003estable-gu-0081\u003c/Value\u003e\n \u003c/ExternalIdentifier\u003e\n \u003cExternalIdentifier\u003e\n \u003cType\u003eocd-id\u003c/Type\u003e\n \u003cValue\u003eocd-division/country:ke/county:narok\u003c/Value\u003e\n \u003c/ExternalIdentifier\u003e\n \u003cExternalIdentifier\u003e\n \u003cType\u003enational-level\u003c/Type\u003e\n \u003cValue\u003e33\u003c/Value\u003e\n \u003c/ExternalIdentifier\u003e\n \u003c/ExternalIdentifiers\u003e\n```\n\n### JSON\n\n```json\n \"ExternalIdentifiers\": {\n \"ExternalIdentifier\" : [\n {\n \"Type\": \"other\",\n \"OtherType\": \"stable\",\n \"Value\": \"stable-gu-0081\"\n },\n {\n \"Type\": \"ocd-id\",\n \"Value\": \"ocd-division/country:ke/county:narok\"\n },\n {\n \"Type\": \"national-level\",\n \"Value\": \"33\"\n }\n ]\n }\n```"]]