--- title: entities.phone description: Read phone records with the phone repository, and change them with the phone mutations. Same records as the REST Phones entity. canonical: https://developers.coevera.com/reference/graphql/phone/ section: graphql verification: schema generatedFrom: schema f155746 (2026-10-20) publisher: Coevera --- # entities.phone Read phone records with the phone repository, and change them with the phone mutations. Same records as the REST Phones entity. REST: [Phones](https://developers.coevera.com/reference/rest/phones.md). ## Queries - `getById(entityId: ID!): PhoneEntity` Returns the record with the given id, or null when there is none. Deleted records are returned as well. - `getByIds(entityIds: [ID!]!): [PhoneEntity!]!` Returns the records with the given ids; ids without a record are left out. Deleted records are returned as well. - `getAll(limit: Int, offset: Int, filter: PhoneFilterInput, orderBy: [PhoneOrderByInput!], includeDeleted: Boolean): [PhoneEntity!]!` Returns the records that match the filter, paged with limit and offset. - `getByCriteria(filter: PhoneFilterInput, orderBy: [PhoneOrderByInput!], includeDeleted: Boolean, before: String, after: String, first: Int, last: Int): PhoneEntityConnection` Returns the records that match the filter as a cursor-paginated connection. - `getChangedFieldsSinceRevision(id: UUID!, revision: Int!): [UUID!]!` Returns the ids of the fields of a record that changed after the given revision. Returns an empty list for entities without change tracking. - `getAllForAdmin(limit: Int, offset: Int, filter: PhoneFilterInput, orderBy: [PhoneOrderByInput!], includeDeleted: Boolean): [PhoneEntity!]!` Returns all phone numbers of the space, including other users' numbers, for administration. - `checkForUnsubscribed(recipients: [SendTextMessageRecipientParams!]!): [SendTextMessageRecipient!]!` Returns the recipients from the given list who have unsubscribed from text messages, so they can be removed before sending. ## Mutations - `createPhone(input: CreatePhoneInput!, validationLevel: [ValidationLevel!]): CreatePhonePayload` Create one record. - `updatePhone(input: UpdatePhoneInput!, validationLevel: [ValidationLevel!], sessionIdToUpdate: String): UpdatePhonePayload` Update fields. - `bulkUpdatePhone(input: [CreateOrUpdatePhoneInput!]!, deleteInput: [DeletePhoneInput!], validationLevel: [ValidationLevel!], rollbackMethod: RollbackMethod, match: MatchingInput): BulkUpdatePhonePayload` Create or update many; per-item results. - `deletePhone(input: DeletePhoneInput!): DeletePhonePayload` Soft-delete. - `updateMessagingPhone(input: UpdatePhoneInput!, validationLevel: [ValidationLevel!], sessionIdToUpdate: String): UpdateMessagingPhonePayload` Updates a WhatsApp phone. Only WhatsApp phones can be updated this way, and their forwarding settings cannot be set. GraphQL only. - `deleteMessagingPhone(input: DeletePhoneInput!): DeleteMessagingPhonePayload` Deletes a WhatsApp phone and disconnects its WhatsApp account from the space. Only WhatsApp phones can be deleted this way. GraphQL only. - `enableMessagingPhone(input: UpdatePhoneInput!): EnableMessagingPhonePayload` Re-enables a WhatsApp phone that was disabled. Fails when the phone is in an error state. GraphQL only. - `disableMessagingPhone(input: UpdatePhoneInput!): DisableMessagingPhonePayload` Disables a WhatsApp phone without deleting it; enableMessagingPhone turns it back on. Fails when the phone is in an error state. GraphQL only. ## Types ### PhoneEntity (object) Phone number connected to Coevera for calls, text messages or WhatsApp, either personal to a user or shared by the company. - `isDeleteProtected: Boolean!` True when the record is protected against deletion because it must always exist in the space. Deleting a record that is not protected can still fail on other checks. Read-only. - `id: ID!` Unique identifier of entity. - `isDeleted: Boolean` Specifies if the entity is considered deleted. - `modified: DateTime` Last modification time. - `created: DateTime` Creation time. - `owner: ClientEntity` User the phone is assigned to, when the phone belongs to a specific user (personal calling/SMS line). - `errorCode: Int` Error code recorded for the phone, set on integration failures (e.g. provider rejected the last send) or when the user disables the integration; empty when the phone is healthy. - `name: String!` Name of the entity and its default text representation. - `ownerId: ID` Id of the assigned user, or empty when the phone is a company-level resource. - `phoneNumber: String` Phone number in E.164 format (e.g. "+12025550123"). - `twilioCallerSid: String` External caller identifier from the calling provider (e.g. Twilio caller SID). - `type: PhoneTypeEnum!` Channel and assignment of the phone number: calling only, calling and SMS (unassigned, personal to the owner or shared by the company), or a personal or company WhatsApp account. - `revision: Int` Revision when entity was lastly changed. - `messageForwardingEmail: String` Email address that incoming text messages to this phone are forwarded to. Empty when forwarding is not configured. - `callForwardingPhone: String` Phone number that incoming calls/SMS to this phone are forwarded to. Empty when forwarding is not configured. - `enabled: Boolean!` False when the user has disabled the calling/SMS integration on this phone (errorCode is set to indicate user disablement); true otherwise. - `instancePermissions: [EntityPermsEnum!]! (1 args)` Permissions the current user has on this record, out of the requested ones. ### PhoneEntityConnection (object) Paginated list of Phone records. - `pageInfo: PageInfo!` Pagination data for this connection. - `edges: [PhoneEntityEdge]!` Contains the nodes in this connection. - `totalCount: Int` Total number of items in the connection. ### PhoneEntityEdge (object) A Relay edge containing a `PhoneEntity` and its cursor. - `node: PhoneEntity` The item at the end of the edge - `cursor: String!` A cursor for use in pagination ### PhoneFilterInput (input) Filter conditions for Phone records. Conditions on different fields are combined with AND; use OR, AND and NOT for other combinations. - `OR: [PhoneFilterInput!]` Matches records that meet at least one of the listed filters. - `AND: [PhoneFilterInput!]` Matches records that meet all of the listed filters. - `NOT: PhoneFilterInput` Matches records that do not meet this filter. - `globalSearchQuery: String` Search term matched against the fields that the global search covers for this entity. - `id: EntityFilterStringField` Unique identifier of entity. - `isDeleted: Boolean` Specifies if the entity is considered deleted. - `modified: EntityFilterDateTimeField` Last modification time. - `created: EntityFilterDateTimeField` Creation time. - `errorCode: EntityFilterNumberField` Error code recorded for the phone, set on integration failures (e.g. provider rejected the last send) or when the user disables the integration; empty when the phone is healthy. - `name: EntityFilterStringField` Name of the entity and its default text representation. - `ownerId: EntityFilterStringField` Id of the assigned user, or empty when the phone is a company-level resource. - `phoneNumber: EntityFilterStringField` Phone number in E.164 format (e.g. "+12025550123"). - `twilioCallerSid: EntityFilterStringField` External caller identifier from the calling provider (e.g. Twilio caller SID). - `type: PhoneTypeEnumFilterInput` Channel and assignment of the phone number: calling only, calling and SMS (unassigned, personal to the owner or shared by the company), or a personal or company WhatsApp account. - `revision: EntityFilterNumberField` Revision when entity was lastly changed. - `enabled: Boolean` False when the user has disabled the calling/SMS integration on this phone (errorCode is set to indicate user disablement); true otherwise. - `owner: ClientFilterInput` User the phone is assigned to, when the phone belongs to a specific user (personal calling/SMS line). Matches records where a related record meets these conditions. ### PhoneOrderByInput (input) Sorting of Phone records. Set exactly one field in each item; list several items to sort by more fields, in order of priority. - `id: OrderByEnum` Unique identifier of entity. - `isDeleted: OrderByEnum` Specifies if the entity is considered deleted. - `modified: OrderByEnum` Last modification time. - `created: OrderByEnum` Creation time. - `owner: [ClientOrderByNestedInput!]` User the phone is assigned to, when the phone belongs to a specific user (personal calling/SMS line). Sorts by fields of the related record, listed in order of priority. - `errorCode: OrderByEnum` Error code recorded for the phone, set on integration failures (e.g. provider rejected the last send) or when the user disables the integration; empty when the phone is healthy. - `name: OrderByEnum` Name of the entity and its default text representation. - `ownerId: OrderByEnum` Id of the assigned user, or empty when the phone is a company-level resource. - `phoneNumber: OrderByEnum` Phone number in E.164 format (e.g. "+12025550123"). - `twilioCallerSid: OrderByEnum` External caller identifier from the calling provider (e.g. Twilio caller SID). - `type: OrderByEnum` Channel and assignment of the phone number: calling only, calling and SMS (unassigned, personal to the owner or shared by the company), or a personal or company WhatsApp account. - `revision: OrderByEnum` Revision when entity was lastly changed. - `enabled: OrderByEnum` False when the user has disabled the calling/SMS integration on this phone (errorCode is set to indicate user disablement); true otherwise. ### PhoneTypeEnumFilterInput (input) Conditions on an enumeration field. Several conditions given together must all match. - `eq: [PhoneTypeEnum!]` Matches any of the listed values. - `NOT: PhoneTypeEnumFilterInput` Matches values that do not meet this condition. ### CreateOrUpdatePhoneInput (input) Field values of a Phone record to create, or to update when its id is set. - `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention). - `id: ID` Unique identifier of entity. - `modified: DateTime` Last modification time. - `created: DateTime` Creation time. - `errorCode: Int` Error code recorded for the phone, set on integration failures (e.g. provider rejected the last send) or when the user disables the integration; empty when the phone is healthy. - `name: String` Name of the entity and its default text representation. - `ownerId: ID` Id of the assigned user, or empty when the phone is a company-level resource. - `phoneNumber: String` Phone number in E.164 format (e.g. "+12025550123"). - `twilioCallerSid: String` External caller identifier from the calling provider (e.g. Twilio caller SID). - `type: PhoneTypeEnum` Channel and assignment of the phone number: calling only, calling and SMS (unassigned, personal to the owner or shared by the company), or a personal or company WhatsApp account. - `revision: Int` Revision when entity was lastly changed. - `enabled: Boolean` False when the user has disabled the calling/SMS integration on this phone (errorCode is set to indicate user disablement); true otherwise. ### CreatePhoneInput (input) Field values of a new Phone record. - `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention). - `modified: DateTime` Last modification time. - `created: DateTime` Creation time. - `errorCode: Int` Error code recorded for the phone, set on integration failures (e.g. provider rejected the last send) or when the user disables the integration; empty when the phone is healthy. - `name: String!` Name of the entity and its default text representation. - `ownerId: ID` Id of the assigned user, or empty when the phone is a company-level resource. - `phoneNumber: String` Phone number in E.164 format (e.g. "+12025550123"). - `twilioCallerSid: String` External caller identifier from the calling provider (e.g. Twilio caller SID). - `type: PhoneTypeEnum!` Channel and assignment of the phone number: calling only, calling and SMS (unassigned, personal to the owner or shared by the company), or a personal or company WhatsApp account. - `revision: Int` Revision when entity was lastly changed. - `enabled: Boolean!` False when the user has disabled the calling/SMS integration on this phone (errorCode is set to indicate user disablement); true otherwise. ### DeletePhoneInput (input) Id of the Phone record to delete. - `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention). - `id: ID!` Unique identifier of entity. ### SendTextMessageRecipientParams (input) Recipient of a text message: the phone number and the records whose data fill its placeholders. - `primary: EntityLacotaType` Which of the given records, such as the Contact or the Account, the message is primarily addressed to. - `opportunityId: UUID` Opportunity whose data fills the opportunity placeholders. - `contactId: UUID` Contact whose data fills the contact placeholders. - `accountId: UUID` Account whose data fills the account placeholders. - `leadId: UUID` Lead whose data fills the lead placeholders. - `projectId: UUID` Project whose data fills the project placeholders. - `quoteId: UUID` Quote whose data fills the quote placeholders. - `customEntityIds: [CustomEntityIDParams]` Custom entity records whose data fill the custom entity placeholders, each given as a `CustomEntityID`. - `phoneNumber: String!` Phone number the text message is sent to. ### UpdatePhoneInput (input) Id of a Phone record and the field values to change. - `id: ID!` Id of the phone. - `ownerId: ID` Id of the user the phone is assigned to. - `created: DateTime` Time the phone was created. - `modified: DateTime` Time the phone was last modified. - `name: String` Display name of the phone. - `phoneNumber: String` Phone number in E.164 format (e.g. "+12025550123"). - `twilioCallerSid: String` Identifier of the phone at the calling provider. - `type: PhoneTypeEnum` Kind of phone: calling only, calling and text messaging (personal, company or unassigned), or WhatsApp (personal or company). - `forwardCallsToPhone: String` Phone number that incoming calls and text messages are forwarded to. - `forwardMessagesToEmail: String` Email address that incoming text messages are forwarded to. - `isDeleted: Boolean` True to remove the phone. Only used when phones are synchronized from the subscription's calling settings. ### BulkUpdatePhonePayload (object) Result of the bulkUpdatePhone mutation. - `result: BulkUpdateResults!` Ids of the created, updated and deleted records, and the items that failed. ### CreatePhonePayload (object) Result of the createPhone mutation. - `phone: PhoneEntity` The created record. - `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention). ### DeleteMessagingPhonePayload (object) Result of the deleteMessagingPhone mutation. - `phone: PhoneEntity` The deleted phone. - `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention). ### DeletePhonePayload (object) Result of the deletePhone mutation. - `phone: PhoneEntity` The deleted record. - `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention). ### DisableMessagingPhonePayload (object) Result of the disableMessagingPhone mutation. - `phone: PhoneEntity` The updated phone. ### EnableMessagingPhonePayload (object) Result of the enableMessagingPhone mutation. - `phone: PhoneEntity` The updated phone. ### UpdateMessagingPhonePayload (object) Result of the updateMessagingPhone mutation. - `phone: PhoneEntity` The updated phone. ### UpdatePhonePayload (object) Result of the updatePhone mutation. - `phone: PhoneEntity` The updated record. ### PhoneTypeEnum (enum) Purpose and assignment of a phone number connected to the space. - `Calling` Number used for voice calls only. - `CallingSmsUnassigned` Calling and SMS number not assigned to any user or to the company. - `CallingSmsPersonal` Calling and SMS number assigned to a single user. - `CallingSmsCompany` Shared company calling and SMS number. - `WhatsAppPersonal` WhatsApp account of a single user. - `WhatsAppCompany` Shared company WhatsApp account. ### SendTextMessageRecipient (object) Recipient of a text message: the phone number and the records whose data fill its placeholders. - `primary: EntityLacotaType` Which of the given records, such as the Contact or the Account, the message is primarily addressed to. - `opportunityId: UUID` Opportunity whose data fills the opportunity placeholders. - `contactId: UUID` Contact whose data fills the contact placeholders. - `accountId: UUID` Account whose data fills the account placeholders. - `leadId: UUID` Lead whose data fills the lead placeholders. - `projectId: UUID` Project whose data fills the project placeholders. - `quoteId: UUID` Quote whose data fills the quote placeholders. - `customEntityIds: [CustomEntityID]` Custom entity records whose data fill the custom entity placeholders, each given as a `CustomEntityID`. - `phoneNumber: String!` Phone number the text message is sent to. Types several repositories share, such as `PageInfo` and the filter fields, are in the [types index](https://developers.coevera.com/reference/graphql/types.md). The [SDL](https://developers.coevera.com/graphql/schema.graphql) has the whole schema in one file. ## Example ```graphql query FirstPhones { entities { phone { getByCriteria(first: 3, orderBy: [{ modified: Desc }]) { totalCount edges { node { id name modified } } } } } } ``` ```bash curl 'https://{region}.api.coevera.com/api/v100/app/space/{space_id}/graphql/public' \ --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \ --header 'Content-Type: application/json' \ --data '{"query":"query FirstPhones { entities { phone { getByCriteria(first: 3, orderBy: [{ modified: Desc }]) { totalCount edges { node { id name modified } } } } } }"}' ```