US Core Implementation Guide, published by HL7 International / Cross-Group Projects. This guide is not an authorized publication; it is the continuous build for version 8.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/US-Core/ and changes regularly. See the Directory of published versions
Official URL: http://hl7.org/fhir/us/core/StructureDefinition/us-core-goal | Version: 8.0.0-ballot | |||
Standards status: Trial-use | Maturity Level: 3 | Computable Name: USCoreGoalProfile | ||
Other Identifiers: OID:2.16.840.1.113883.4.642.40.2.42.28 | ||||
Copyright/Legal: Used by permission of HL7 International, all rights reserved Creative Commons License |
The US Core Goal Profile inherits from the FHIR Goal resource; refer to it for scope and usage definitions. This profile sets minimum expectations for the Goal resource to record, search, and fetch Goal information associated with a patient. It specifies which core elements, extensions, vocabularies, and value sets SHALL be present and constrains how the elements are used. Providing the floor for standards development for specific use cases promotes interoperability and adoption.
Example Usage Scenarios:
The following are example usage scenarios for this profile:
The following data elements must always be present (Mandatory definition) or must be supported if the data is present in the sending system (Must Support definition). They are presented below in a simple human-readable explanation. Profile specific guidance and examples are provided as well. The Formal Views below provides the formal summary, definitions, and terminology requirements.
Each Goal Must Have:
Each Goal Must Support:
*see guidance below
Profile Specific Implementation Guidance:
Goal.startDate
and Goal.target.dueDate
are marked as Must Support, the Server system is not required to support both, but SHALL support at least one of these elements. The Client application SHALL support both elements.Goal.description.text
. When the goal is a Social Determinants of Health (SDOH) goal, use the preferred Social Determinants of Health Goals binding.Goal.expressedBy
communicate the individual level provenance author data corresponding to the U.S. Core Data for Interoperability (USCDI) Provenance Author Data Elements.Usage:
Changes since version 7.0.0:
Description of Profiles, Differentials, Snapshots and how the different presentations work.
This structure is derived from Goal
Name | Flags | Card. | Type | Description & Constraints | ||||
---|---|---|---|---|---|---|---|---|
Goal | 0..* | Goal | Describes the intended objective(s) for a patient, group or organization | |||||
lifecycleStatus | S | 1..1 | code | proposed | planned | accepted | active | on-hold | completed | cancelled | entered-in-error | rejected Binding: GoalLifecycleStatus (required) | ||||
description | S | 1..1 | CodeableConcept | Code or text describing goal Binding: US Core Goal Codes (preferred): Value set to describe the Goal
| ||||
subject | S | 1..1 | Reference(US Core Patient Profile S | Group | Organization) | Who this goal is intended for | ||||
start[x] | S | 0..1 | When goal pursuit begins | |||||
startDate | date S | |||||||
startCodeableConcept | CodeableConcept | |||||||
target | S | 0..* | BackboneElement | Target outcome for the goal | ||||
due[x] | S | 0..1 | Reach goal on or before | |||||
dueDate | date S | |||||||
dueDuration | Duration | |||||||
expressedBy | S | 0..1 | Reference(US Core Practitioner Profile S | US Core Patient Profile | PractitionerRole | US Core RelatedPerson Profile) | Who's responsible for creating Goal? | ||||
Documentation for this format |
Path | Conformance | ValueSet | URI |
Goal.lifecycleStatus | required | GoalLifecycleStatushttp://hl7.org/fhir/ValueSet/goal-status from the FHIR Standard | |
Goal.description | preferred | USCoreGoalCodeshttp://hl7.org/fhir/us/core/ValueSet/us-core-goal-description from this IG |
Name | Flags | Card. | Type | Description & Constraints | ||||
---|---|---|---|---|---|---|---|---|
Goal | 0..* | Goal | Describes the intended objective(s) for a patient, group or organization dom-2: If the resource is contained in another resource, it SHALL NOT contain nested Resources dom-3: If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource dom-4: If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated dom-5: If a resource is contained in another resource, it SHALL NOT have a security label dom-6: A resource should have narrative for robust management | |||||
implicitRules | ?!Σ | 0..1 | uri | A set of rules under which this content was created ele-1: All FHIR elements must have a @value or children | ||||
modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored ele-1: All FHIR elements must have a @value or children ext-1: Must have either extensions or value[x], not both | ||||
lifecycleStatus | ?!SΣ | 1..1 | code | proposed | planned | accepted | active | on-hold | completed | cancelled | entered-in-error | rejected Binding: GoalLifecycleStatus (required) ele-1: All FHIR elements must have a @value or children | ||||
description | SΣ | 1..1 | CodeableConcept | Code or text describing goal Binding: US Core Goal Codes (preferred): Value set to describe the Goal
ele-1: All FHIR elements must have a @value or children | ||||
subject | SΣ | 1..1 | Reference(US Core Patient Profile) | Who this goal is intended for ele-1: All FHIR elements must have a @value or children | ||||
start[x] | SΣ | 0..1 | When goal pursuit begins Binding: GoalStartEvent (example): Codes describing events that can trigger the initiation of a goal. ele-1: All FHIR elements must have a @value or children | |||||
startDate | date | |||||||
target | SC | 0..* | BackboneElement | Target outcome for the goal ele-1: All FHIR elements must have a @value or children gol-1: Goal.target.measure is required if Goal.target.detail is populated | ||||
modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized ele-1: All FHIR elements must have a @value or children ext-1: Must have either extensions or value[x], not both | ||||
due[x] | SΣ | 0..1 | Reach goal on or before ele-1: All FHIR elements must have a @value or children | |||||
dueDate | date | |||||||
expressedBy | SΣ | 0..1 | Reference(US Core Practitioner Profile) | Who's responsible for creating Goal? ele-1: All FHIR elements must have a @value or children | ||||
Documentation for this format |
Path | Conformance | ValueSet | URI |
Goal.lifecycleStatus | required | GoalLifecycleStatushttp://hl7.org/fhir/ValueSet/goal-status from the FHIR Standard | |
Goal.description | preferred | USCoreGoalCodeshttp://hl7.org/fhir/us/core/ValueSet/us-core-goal-description from this IG | |
Goal.start[x] | example | GoalStartEventhttp://hl7.org/fhir/ValueSet/goal-start-event from the FHIR Standard |
Name | Flags | Card. | Type | Description & Constraints | ||||
---|---|---|---|---|---|---|---|---|
Goal | 0..* | Goal | Describes the intended objective(s) for a patient, group or organization | |||||
id | Σ | 0..1 | id | Logical id of this artifact | ||||
meta | Σ | 0..1 | Meta | Metadata about the resource | ||||
implicitRules | ?!Σ | 0..1 | uri | A set of rules under which this content was created | ||||
language | 0..1 | code | Language of the resource content Binding: CommonLanguages (preferred): A human language.
| |||||
text | 0..1 | Narrative | Text summary of the resource, for human interpretation | |||||
contained | 0..* | Resource | Contained, inline Resources | |||||
extension | 0..* | Extension | Additional content defined by implementations | |||||
modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | ||||
identifier | 0..* | Identifier | External Ids for this goal | |||||
lifecycleStatus | ?!SΣ | 1..1 | code | proposed | planned | accepted | active | on-hold | completed | cancelled | entered-in-error | rejected Binding: GoalLifecycleStatus (required) | ||||
achievementStatus | Σ | 0..1 | CodeableConcept | in-progress | improving | worsening | no-change | achieved | sustaining | not-achieved | no-progress | not-attainable Binding: GoalAchievementStatus (preferred): Indicates the progression, or lack thereof, towards the goal against the target. | ||||
category | Σ | 0..* | CodeableConcept | E.g. Treatment, dietary, behavioral, etc. Binding: GoalCategory (example): Codes for grouping and sorting goals. | ||||
priority | Σ | 0..1 | CodeableConcept | high-priority | medium-priority | low-priority Binding: GoalPriority (preferred): The level of importance associated with a goal. | ||||
description | SΣ | 1..1 | CodeableConcept | Code or text describing goal Binding: US Core Goal Codes (preferred): Value set to describe the Goal
| ||||
subject | SΣ | 1..1 | Reference(US Core Patient Profile S | Group | Organization) | Who this goal is intended for | ||||
start[x] | SΣ | 0..1 | When goal pursuit begins Binding: GoalStartEvent (example): Codes describing events that can trigger the initiation of a goal. | |||||
startDate | date S | |||||||
startCodeableConcept | CodeableConcept | |||||||
target | SC | 0..* | BackboneElement | Target outcome for the goal gol-1: Goal.target.measure is required if Goal.target.detail is populated | ||||
id | 0..1 | string | Unique id for inter-element referencing | |||||
extension | 0..* | Extension | Additional content defined by implementations | |||||
modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
measure | ΣC | 0..1 | CodeableConcept | The parameter whose value is being tracked Binding: LOINCCodes (example): Codes to identify the value being tracked, e.g. body weight, blood pressure, or hemoglobin A1c level. | ||||
detail[x] | ΣC | 0..1 | The target value to be achieved Binding Description (No ValueSet): (example): Codes to identify the target value of the focus to be achieved to signify the fulfillment of the goal. | |||||
detailQuantity | Quantity | |||||||
detailRange | Range | |||||||
detailCodeableConcept | CodeableConcept | |||||||
detailString | string | |||||||
detailBoolean | boolean | |||||||
detailInteger | integer | |||||||
detailRatio | Ratio | |||||||
due[x] | SΣ | 0..1 | Reach goal on or before | |||||
dueDate | date S | |||||||
dueDuration | Duration | |||||||
statusDate | Σ | 0..1 | date | When goal status took effect | ||||
statusReason | 0..1 | string | Reason for current status | |||||
expressedBy | SΣ | 0..1 | Reference(US Core Practitioner Profile S | US Core Patient Profile | PractitionerRole | US Core RelatedPerson Profile) | Who's responsible for creating Goal? | ||||
addresses | 0..* | Reference(Condition | Observation | MedicationStatement | NutritionOrder | ServiceRequest | RiskAssessment) | Issues addressed by this goal | |||||
note | 0..* | Annotation | Comments about the goal | |||||
outcomeCode | 0..* | CodeableConcept | What result was achieved regarding the goal? Binding: SNOMEDCTClinicalFindings (example): The result of the goal; e.g. "25% increase in shoulder mobility", "Anxiety reduced to moderate levels". "15 kg weight loss sustained over 6 months". | |||||
outcomeReference | 0..* | Reference(Observation) | Observation that resulted from goal | |||||
Documentation for this format |
Path | Conformance | ValueSet | URI | |||
Goal.language | preferred | CommonLanguageshttp://hl7.org/fhir/ValueSet/languages from the FHIR Standard
| ||||
Goal.lifecycleStatus | required | GoalLifecycleStatushttp://hl7.org/fhir/ValueSet/goal-status from the FHIR Standard | ||||
Goal.achievementStatus | preferred | GoalAchievementStatushttp://hl7.org/fhir/ValueSet/goal-achievement from the FHIR Standard | ||||
Goal.category | example | GoalCategoryhttp://hl7.org/fhir/ValueSet/goal-category from the FHIR Standard | ||||
Goal.priority | preferred | GoalPriorityhttp://hl7.org/fhir/ValueSet/goal-priority from the FHIR Standard | ||||
Goal.description | preferred | USCoreGoalCodeshttp://hl7.org/fhir/us/core/ValueSet/us-core-goal-description from this IG | ||||
Goal.start[x] | example | GoalStartEventhttp://hl7.org/fhir/ValueSet/goal-start-event from the FHIR Standard | ||||
Goal.target.measure | example | LOINCCodes (a valid code from LOINC)http://hl7.org/fhir/ValueSet/observation-codes from the FHIR Standard | ||||
Goal.target.detail[x] | example | |||||
Goal.outcomeCode | example | SNOMEDCTClinicalFindingshttp://hl7.org/fhir/ValueSet/clinical-findings from the FHIR Standard |
This structure is derived from Goal
Summary
Must-Support: 7 elements
Structures
This structure refers to these other structures:
Maturity: 3
Differential View
This structure is derived from Goal
Name | Flags | Card. | Type | Description & Constraints | ||||
---|---|---|---|---|---|---|---|---|
Goal | 0..* | Goal | Describes the intended objective(s) for a patient, group or organization | |||||
lifecycleStatus | S | 1..1 | code | proposed | planned | accepted | active | on-hold | completed | cancelled | entered-in-error | rejected Binding: GoalLifecycleStatus (required) | ||||
description | S | 1..1 | CodeableConcept | Code or text describing goal Binding: US Core Goal Codes (preferred): Value set to describe the Goal
| ||||
subject | S | 1..1 | Reference(US Core Patient Profile S | Group | Organization) | Who this goal is intended for | ||||
start[x] | S | 0..1 | When goal pursuit begins | |||||
startDate | date S | |||||||
startCodeableConcept | CodeableConcept | |||||||
target | S | 0..* | BackboneElement | Target outcome for the goal | ||||
due[x] | S | 0..1 | Reach goal on or before | |||||
dueDate | date S | |||||||
dueDuration | Duration | |||||||
expressedBy | S | 0..1 | Reference(US Core Practitioner Profile S | US Core Patient Profile | PractitionerRole | US Core RelatedPerson Profile) | Who's responsible for creating Goal? | ||||
Documentation for this format |
Path | Conformance | ValueSet | URI |
Goal.lifecycleStatus | required | GoalLifecycleStatushttp://hl7.org/fhir/ValueSet/goal-status from the FHIR Standard | |
Goal.description | preferred | USCoreGoalCodeshttp://hl7.org/fhir/us/core/ValueSet/us-core-goal-description from this IG |
Key Elements View
Name | Flags | Card. | Type | Description & Constraints | ||||
---|---|---|---|---|---|---|---|---|
Goal | 0..* | Goal | Describes the intended objective(s) for a patient, group or organization dom-2: If the resource is contained in another resource, it SHALL NOT contain nested Resources dom-3: If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource dom-4: If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated dom-5: If a resource is contained in another resource, it SHALL NOT have a security label dom-6: A resource should have narrative for robust management | |||||
implicitRules | ?!Σ | 0..1 | uri | A set of rules under which this content was created ele-1: All FHIR elements must have a @value or children | ||||
modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored ele-1: All FHIR elements must have a @value or children ext-1: Must have either extensions or value[x], not both | ||||
lifecycleStatus | ?!SΣ | 1..1 | code | proposed | planned | accepted | active | on-hold | completed | cancelled | entered-in-error | rejected Binding: GoalLifecycleStatus (required) ele-1: All FHIR elements must have a @value or children | ||||
description | SΣ | 1..1 | CodeableConcept | Code or text describing goal Binding: US Core Goal Codes (preferred): Value set to describe the Goal
ele-1: All FHIR elements must have a @value or children | ||||
subject | SΣ | 1..1 | Reference(US Core Patient Profile) | Who this goal is intended for ele-1: All FHIR elements must have a @value or children | ||||
start[x] | SΣ | 0..1 | When goal pursuit begins Binding: GoalStartEvent (example): Codes describing events that can trigger the initiation of a goal. ele-1: All FHIR elements must have a @value or children | |||||
startDate | date | |||||||
target | SC | 0..* | BackboneElement | Target outcome for the goal ele-1: All FHIR elements must have a @value or children gol-1: Goal.target.measure is required if Goal.target.detail is populated | ||||
modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized ele-1: All FHIR elements must have a @value or children ext-1: Must have either extensions or value[x], not both | ||||
due[x] | SΣ | 0..1 | Reach goal on or before ele-1: All FHIR elements must have a @value or children | |||||
dueDate | date | |||||||
expressedBy | SΣ | 0..1 | Reference(US Core Practitioner Profile) | Who's responsible for creating Goal? ele-1: All FHIR elements must have a @value or children | ||||
Documentation for this format |
Path | Conformance | ValueSet | URI |
Goal.lifecycleStatus | required | GoalLifecycleStatushttp://hl7.org/fhir/ValueSet/goal-status from the FHIR Standard | |
Goal.description | preferred | USCoreGoalCodeshttp://hl7.org/fhir/us/core/ValueSet/us-core-goal-description from this IG | |
Goal.start[x] | example | GoalStartEventhttp://hl7.org/fhir/ValueSet/goal-start-event from the FHIR Standard |
Snapshot View
Name | Flags | Card. | Type | Description & Constraints | ||||
---|---|---|---|---|---|---|---|---|
Goal | 0..* | Goal | Describes the intended objective(s) for a patient, group or organization | |||||
id | Σ | 0..1 | id | Logical id of this artifact | ||||
meta | Σ | 0..1 | Meta | Metadata about the resource | ||||
implicitRules | ?!Σ | 0..1 | uri | A set of rules under which this content was created | ||||
language | 0..1 | code | Language of the resource content Binding: CommonLanguages (preferred): A human language.
| |||||
text | 0..1 | Narrative | Text summary of the resource, for human interpretation | |||||
contained | 0..* | Resource | Contained, inline Resources | |||||
extension | 0..* | Extension | Additional content defined by implementations | |||||
modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | ||||
identifier | 0..* | Identifier | External Ids for this goal | |||||
lifecycleStatus | ?!SΣ | 1..1 | code | proposed | planned | accepted | active | on-hold | completed | cancelled | entered-in-error | rejected Binding: GoalLifecycleStatus (required) | ||||
achievementStatus | Σ | 0..1 | CodeableConcept | in-progress | improving | worsening | no-change | achieved | sustaining | not-achieved | no-progress | not-attainable Binding: GoalAchievementStatus (preferred): Indicates the progression, or lack thereof, towards the goal against the target. | ||||
category | Σ | 0..* | CodeableConcept | E.g. Treatment, dietary, behavioral, etc. Binding: GoalCategory (example): Codes for grouping and sorting goals. | ||||
priority | Σ | 0..1 | CodeableConcept | high-priority | medium-priority | low-priority Binding: GoalPriority (preferred): The level of importance associated with a goal. | ||||
description | SΣ | 1..1 | CodeableConcept | Code or text describing goal Binding: US Core Goal Codes (preferred): Value set to describe the Goal
| ||||
subject | SΣ | 1..1 | Reference(US Core Patient Profile S | Group | Organization) | Who this goal is intended for | ||||
start[x] | SΣ | 0..1 | When goal pursuit begins Binding: GoalStartEvent (example): Codes describing events that can trigger the initiation of a goal. | |||||
startDate | date S | |||||||
startCodeableConcept | CodeableConcept | |||||||
target | SC | 0..* | BackboneElement | Target outcome for the goal gol-1: Goal.target.measure is required if Goal.target.detail is populated | ||||
id | 0..1 | string | Unique id for inter-element referencing | |||||
extension | 0..* | Extension | Additional content defined by implementations | |||||
modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
measure | ΣC | 0..1 | CodeableConcept | The parameter whose value is being tracked Binding: LOINCCodes (example): Codes to identify the value being tracked, e.g. body weight, blood pressure, or hemoglobin A1c level. | ||||
detail[x] | ΣC | 0..1 | The target value to be achieved Binding Description (No ValueSet): (example): Codes to identify the target value of the focus to be achieved to signify the fulfillment of the goal. | |||||
detailQuantity | Quantity | |||||||
detailRange | Range | |||||||
detailCodeableConcept | CodeableConcept | |||||||
detailString | string | |||||||
detailBoolean | boolean | |||||||
detailInteger | integer | |||||||
detailRatio | Ratio | |||||||
due[x] | SΣ | 0..1 | Reach goal on or before | |||||
dueDate | date S | |||||||
dueDuration | Duration | |||||||
statusDate | Σ | 0..1 | date | When goal status took effect | ||||
statusReason | 0..1 | string | Reason for current status | |||||
expressedBy | SΣ | 0..1 | Reference(US Core Practitioner Profile S | US Core Patient Profile | PractitionerRole | US Core RelatedPerson Profile) | Who's responsible for creating Goal? | ||||
addresses | 0..* | Reference(Condition | Observation | MedicationStatement | NutritionOrder | ServiceRequest | RiskAssessment) | Issues addressed by this goal | |||||
note | 0..* | Annotation | Comments about the goal | |||||
outcomeCode | 0..* | CodeableConcept | What result was achieved regarding the goal? Binding: SNOMEDCTClinicalFindings (example): The result of the goal; e.g. "25% increase in shoulder mobility", "Anxiety reduced to moderate levels". "15 kg weight loss sustained over 6 months". | |||||
outcomeReference | 0..* | Reference(Observation) | Observation that resulted from goal | |||||
Documentation for this format |
Path | Conformance | ValueSet | URI | |||
Goal.language | preferred | CommonLanguageshttp://hl7.org/fhir/ValueSet/languages from the FHIR Standard
| ||||
Goal.lifecycleStatus | required | GoalLifecycleStatushttp://hl7.org/fhir/ValueSet/goal-status from the FHIR Standard | ||||
Goal.achievementStatus | preferred | GoalAchievementStatushttp://hl7.org/fhir/ValueSet/goal-achievement from the FHIR Standard | ||||
Goal.category | example | GoalCategoryhttp://hl7.org/fhir/ValueSet/goal-category from the FHIR Standard | ||||
Goal.priority | preferred | GoalPriorityhttp://hl7.org/fhir/ValueSet/goal-priority from the FHIR Standard | ||||
Goal.description | preferred | USCoreGoalCodeshttp://hl7.org/fhir/us/core/ValueSet/us-core-goal-description from this IG | ||||
Goal.start[x] | example | GoalStartEventhttp://hl7.org/fhir/ValueSet/goal-start-event from the FHIR Standard | ||||
Goal.target.measure | example | LOINCCodes (a valid code from LOINC)http://hl7.org/fhir/ValueSet/observation-codes from the FHIR Standard | ||||
Goal.target.detail[x] | example | |||||
Goal.outcomeCode | example | SNOMEDCTClinicalFindingshttp://hl7.org/fhir/ValueSet/clinical-findings from the FHIR Standard |
This structure is derived from Goal
Summary
Must-Support: 7 elements
Structures
This structure refers to these other structures:
Maturity: 3
Other representations of profile: CSV, Excel, Schematron
Below is an overview of the required Server RESTful FHIR interactions for this profile - for example, search and read operations - when supporting the US Core interactions to access this profile's information (Profile Support + Interaction Support). Note that systems that support only US Core Profiles (Profile Only Support) are not required to support these interactions. See the US Core Server CapabilityStatement for a complete list of supported RESTful interactions for this IG.
Servers providing access to goal data SHALL support these US Core SMART Scopes:
<patient|user|system>/Goal.rs
The following search parameters and search parameter combinations SHALL be supported:
SHALL support searching for all goals for a patient using the patient
search parameter:
GET [base]/Goal?patient={Type/}[id]
Example:
Implementation Notes: Fetches a bundle of all Goal resources for the specified patient (how to search by reference)
The following search parameter combinations SHOULD be supported:
SHOULD support searching using the combination of the patient
and lifecycle-status
search parameters:
GET [base]/Goal?patient={Type/}[id]&lifecycle-status={system|}[code]
Example:
Implementation Notes: Fetches a bundle of all Goal resources for the specified patient and lifecycle-status (how to search by reference and how to search by token)
patient
and target-date
search parameters:
target-date
comparators: gt,lt,ge,le
target-date
(e.g.target-date=[date]&target-date=[date]]&...
)GET [base]/Goal?patient={Type/}[id]&target-date={gt|lt|ge|le}[date]{&target-date={gt|lt|ge|le}[date]&...}
Example:
Implementation Notes: Fetches a bundle of all Goal resources for the specified patient and target-date (how to search by reference and how to search by date)
SHOULD support searching using the combination of the patient
and description
search parameters:
GET [base]/Goal?patient={Type/}[id]&description={system|}[code]
Example:
Implementation Notes: Fetches a bundle of all Goal resources for the specified patient and description (how to search by reference and how to search by token)