openapi: 3.2.0 info: description: Close CRM REST API title: Close Phone Numbers API version: 1.0.0 servers: - url: https://api.close.com/api/v1 security: - ApiKeyAuth: [] - OAuth2: [] tags: - name: phone_numbers externalDocs: url: https://developer.close.com/api/resources/phone-numbers paths: /phone_number/: get: operationId: phone_numbers_list tags: - phone_numbers summary: List or search for phone numbers parameters: - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/SkipParam' - $ref: '#/components/parameters/FieldsParam' - in: query name: number required: false schema: title: Number default: null anyOf: - type: string - type: 'null' - in: query name: user_id required: false description: Deprecated. Use `participant_user_id` instead. The distinction between personal and group numbers is being removed, and `user_id` will be removed in a future update. schema: title: User ID default: null anyOf: - type: string - type: 'null' deprecated: true - in: query name: is_group_number required: false description: Deprecated. Use `participant_user_id` instead. The distinction between personal and group numbers is being removed, and `is_group_number` will be removed in a future update. schema: title: Is Group Number default: null anyOf: - type: boolean - type: 'null' deprecated: true - in: query name: participant_user_id required: false description: Return numbers the given user participates in, including both personal and group numbers they belong to. schema: title: Participant User ID default: null anyOf: - type: string - type: 'null' responses: '200': content: application/json: example: data: - address_id: null bundle_id: null carrier: null carrier_type: null country: US date_created: '2016-07-18T22:54:24.787000+00:00' date_updated: '2016-07-18T22:55:55.938000+00:00' forward_to: null forward_to_enabled: false forward_to_formatted: null id: phon_asdjkfev50ZKOqTVndOFN4effzv99vDvpDxrks9XLU3 inbound_ring_duration: null is_group_number: false is_premium: false is_verified: true label: Primary Number last_billed_price: null mms_enabled: true next_billing_on: null number: '+16503335555' number_formatted: +1 650-333-5555 organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH participants: [] phone_numbers: - '+16508889898' phone_numbers_formatted: - +1 650-888-9898 press_1_to_accept: false sms_enabled: true supports_mms_to_countries: - CA - US supports_sms_to_countries: - CA - US type: internal user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA voicemail_greeting_url: null was_ported: false - address_id: null bundle_id: null carrier: null carrier_type: null country: US date_created: '2016-07-18T22:54:24.787000+00:00' date_updated: '2016-07-18T22:55:55.938000+00:00' forward_to: null forward_to_enabled: false forward_to_formatted: null id: phon_973589ev50ZKOqTVndOFN4effz092753608234569U3 is_group_number: false is_premium: false is_verified: true label: My Personal Cell last_billed_price: null mms_enabled: true next_billing_on: null number: '+14151231234' number_formatted: +1 415-123-1234 organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH participants: [] phone_numbers: [] phone_numbers_formatted: [] press_1_to_accept: false sms_enabled: false supports_mms_to_countries: - CA - US supports_sms_to_countries: [] type: external user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA voicemail_greeting_url: null was_ported: false - address_id: null bundle_id: null carrier: null carrier_type: null country: US date_created: '2016-07-14T20:37:23.022000+00:00' date_updated: '2016-07-18T22:54:41.548000+00:00' forward_to: null forward_to_enabled: false forward_to_formatted: null id: phon_324230958beOjoa6F42w5Hlkdjfg8p3wmIPnTuvNbaX inbound_ring_duration: null is_group_number: true is_premium: false is_verified: true label: Group Number last_billed_price: null mms_enabled: true next_billing_on: null number: '+16508881234' number_formatted: +1 650-888-1234 organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH participants: - user_OWiN4rEbBR04K2AKXe3jq5j1JWQqmTguuuZa1dG7qQr - user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk - user_SJMF1fEyZGdtl2RPzCm9zVQ7qhd33VajdGDREhbsxjF phone_numbers: [] phone_numbers_formatted: [] press_1_to_accept: false sms_enabled: true supports_mms_to_countries: - CA - US supports_sms_to_countries: - CA - US type: internal user_id: null voicemail_greeting_url: null has_more: false schema: type: object properties: data: items: $ref: '#/components/schemas/PhoneNumber' type: array has_more: type: boolean required: - data - has_more description: Successful response '400': description: Bad request '401': description: Unauthorized '404': description: Not found /phone_number/request/internal/: post: operationId: phone_numbers_create tags: - phone_numbers summary: Request an internal phone number description: "Renting a phone number incurs a cost. You need the \"Manage Team Phone Numbers\" permission to rent group numbers.\n\nIf a number was rented, a 201 response is returned with the new number. If no number was rented (4xx response code), the response contains a `status` field which may contain one of the values below. New statuses may be added in the future.\n\n* `has-voice-only`: This country/prefix combination only has non-SMS-capable\n numbers. You can attempt renting the number by passing `with_sms` as `false`.\n* `needs-more-info`: More information (such as proof of address) is needed to\n rent this number. This number can only be rented by contacting Close support.\n* `billing-error`: An error related to billing has occurred. For example, the\n telephony budget has been reached, or there are not enough funds and recharging failed.\n* `error`: An error has occurred while renting this number. A human-readable\n message is returned in the `error` field." requestBody: content: application/json: example: country: US prefix: '650' sharing: personal schema: $ref: '#/components/schemas/CreatePhoneNumberRequest' required: true responses: '201': content: application/json: example: address_id: null bundle_id: null carrier: null carrier_type: null country: US date_created: '2021-03-17T11:45:56.651057' date_updated: '2021-03-17T11:45:56.651057' forward_to: null forward_to_enabled: false forward_to_formatted: null id: phon_MiLNdBqo8utNOf1U78RaZgQB1Iq6rRGftiDW5C8B9uL inbound_ring_duration: null is_group_number: false is_premium: false is_verified: true label: null last_billed_price: null mms_enabled: true next_billing_on: null number: '+16503335555' number_formatted: +1 650-333-5555 organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH press_1_to_accept: false sms_enabled: true supports_mms_to_countries: - CA - US supports_sms_to_countries: - CA - PR - US type: internal user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA voicemail_greeting_url: null description: Successful response '400': description: Bad request '401': description: Unauthorized '404': description: Not found /phone_number/{id}/: get: operationId: phone_numbers_get tags: - phone_numbers summary: Retrieve a single phone number parameters: - in: path name: id required: true schema: type: string - $ref: '#/components/parameters/FieldsParam' responses: '200': content: application/json: example: address_id: null bundle_id: null carrier: null carrier_type: null country: US date_created: '2016-07-18T22:54:24.787000+00:00' date_updated: '2016-07-18T22:55:55.938000+00:00' forward_to: null forward_to_enabled: false forward_to_formatted: null id: phon_asdjkfev50ZKOqTVndOFN4effzv99vDvpDxrks9XLU3 inbound_ring_duration: null is_group_number: false is_premium: false is_verified: true label: Primary Number last_billed_price: null mms_enabled: true next_billing_on: null number: '+16503335555' number_formatted: +1 650-333-5555 organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH press_1_to_accept: false sms_enabled: true supports_mms_to_countries: - CA - US supports_sms_to_countries: - CA - US type: internal user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA voicemail_greeting_url: null schema: $ref: '#/components/schemas/PhoneNumber' description: Successful response '400': description: Bad request '401': description: Unauthorized '404': description: Not found put: operationId: phone_numbers_update tags: - phone_numbers summary: Update a phone number description: 'You need the "Manage Team Phone Numbers" permission to update a group number. You can only update your own personal numbers. You can: - Change a `label` of your number. - Set up call forwarding via `forward_to` and `forward_to_enabled`. - Set up a voicemail greeting by including a URL of an mp3 recording in `voicemail_greeting_url`. We require the URL to be secure (i.e. starting with https://). - Modify which team members are part of a group number via `participants`. This should be a list of user IDs. - Modify which external phone numbers are part of a group number via `phone_numbers`. This should be a list of phone numbers in E.164 international format, e.g. "+16503334444". - Change how long (in seconds, 15-90) the number rings on inbound calls before moving on (e.g. to voicemail) via `inbound_ring_duration`.' parameters: - in: path name: id required: true schema: type: string requestBody: content: application/json: example: forward_to: '+16502221111' forward_to_enabled: true inbound_ring_duration: 45 label: My number w/ forwarding voicemail_greeting_url: https://s3.amazonaws.com/bucket/aaa-bbb-ccc.mp3 schema: $ref: '#/components/schemas/UpdatePhoneNumber' required: true responses: '200': content: application/json: example: address_id: null bundle_id: null carrier: null carrier_type: null country: US date_created: '2016-07-18T22:54:24.787000+00:00' date_updated: '2016-07-22T22:55:55.938000+00:00' forward_to: '+16502221111' forward_to_enabled: true forward_to_formatted: +1 650-222-1111 id: phon_asdjkfev50ZKOqTVndOFN4effzv99vDvpDxrks9XLU3 inbound_ring_duration: 45 is_group_number: false is_premium: false is_verified: true label: My number w/ forwarding last_billed_price: null mms_enabled: true next_billing_on: null number: '+16503335555' number_formatted: +1 650-333-5555 organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH press_1_to_accept: false sms_enabled: true supports_mms_to_countries: - CA - US supports_sms_to_countries: - CA - US type: internal user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA voicemail_greeting_url: https://s3.amazonaws.com/bucket/aaa-bbb-ccc.mp3 schema: $ref: '#/components/schemas/PhoneNumber' description: Successful response '400': description: Bad request '401': description: Unauthorized '404': description: Not found delete: operationId: phone_numbers_delete tags: - phone_numbers summary: Delete a phone number description: You need the "Manage Team Phone Numbers" permission to delete a group number. You can only delete your own personal numbers. parameters: - in: path name: id required: true schema: type: string responses: '200': description: Successful response '400': description: Bad request '401': description: Unauthorized '404': description: Not found components: parameters: FieldsParam: description: Comma-separated list of fields to include in the response. in: query name: _fields required: false schema: type: string LimitParam: description: Number of results to return. in: query name: _limit required: false schema: default: 100 type: integer SkipParam: description: Number of results to skip before returning, for pagination. in: query name: _skip required: false schema: default: 0 type: integer schemas: CarrierNumberType: title: CarrierNumberType type: string enum: - local - national - mobile - tollfree - shortcode UpdatePhoneNumber: title: UpdatePhoneNumber type: object properties: forward_to: title: Forward To type: string forward_to_enabled: title: Forward To Enabled type: boolean inbound_ring_duration: title: Inbound Ring Duration description: Number of seconds (15-90) to ring this number on inbound calls before moving on (e.g. to voicemail). type: integer minimum: 15 maximum: 90 label: title: Label type: string participants: title: Participants type: array items: type: string phone_numbers: title: Phone Numbers type: array items: type: string press_1_to_accept: title: Press 1 To Accept type: boolean voicemail_greeting_url: title: Voicemail Greeting URL anyOf: - type: string - type: 'null' additionalProperties: false PhoneNumber: title: PhoneNumber type: object properties: address_id: title: Address ID anyOf: - type: string - type: 'null' bundle_id: title: Bundle ID anyOf: - type: string - type: 'null' carrier: anyOf: - $ref: '#/components/schemas/UnderlyingCarrier' - type: 'null' carrier_type: anyOf: - $ref: '#/components/schemas/CarrierNumberType' - type: 'null' country: title: Country anyOf: - type: string - type: 'null' date_created: title: Date Created type: string format: date-time date_updated: title: Date Updated type: string format: date-time forward_to: title: Forward To anyOf: - type: string - type: 'null' forward_to_enabled: title: Forward To Enabled type: boolean forward_to_formatted: title: Forward To Formatted anyOf: - type: string - type: 'null' id: title: ID type: string inbound_ring_duration: title: Inbound Ring Duration description: Number of seconds we ring this number on inbound calls before moving on (e.g. to voicemail). `null` means the default of 30 seconds is used. anyOf: - type: integer - type: 'null' is_group_number: title: Is Group Number description: Deprecated. The distinction between personal and group numbers is being removed, and `is_group_number` will be removed in a future update. deprecated: true type: boolean is_premium: title: Is Premium type: boolean is_verified: title: Is Verified type: boolean label: title: Label type: string last_billed_price: title: Last Billed Price anyOf: - type: number - type: 'null' mms_enabled: title: Mms Enabled type: boolean next_billing_on: title: Next Billing On anyOf: - type: string format: date-time - type: 'null' number: title: Number type: string number_formatted: title: Number Formatted type: string organization_id: title: Organization ID type: string participants: title: Participants type: array items: type: string phone_numbers: title: Phone Numbers type: array items: type: string phone_numbers_formatted: title: Phone Numbers Formatted type: array items: type: string press_1_to_accept: title: Press 1 To Accept type: boolean sms_enabled: title: SMS Enabled type: boolean supports_mms_to_countries: title: Supports Mms To Countries type: array items: type: string supports_sms_to_countries: title: Supports SMS To Countries type: array items: type: string type: $ref: '#/components/schemas/PhoneNumberType' user_id: title: User ID description: Deprecated. Set to the sole member's user ID for single-member numbers, otherwise `null`. `user_id` will be removed in a future update. deprecated: true anyOf: - type: string - type: 'null' voicemail_greeting_url: title: Voicemail Greeting URL anyOf: - type: string - type: 'null' was_ported: title: Was Ported type: boolean required: - address_id - bundle_id - carrier - carrier_type - country - date_created - date_updated - id - is_group_number - is_premium - is_verified - label - last_billed_price - mms_enabled - next_billing_on - number - number_formatted - organization_id - sms_enabled - supports_mms_to_countries - supports_sms_to_countries - type - user_id PhoneNumberSharing: title: PhoneNumberSharing type: string enum: - personal - group UnderlyingCarrier: title: UnderlyingCarrier type: string enum: - twilio - plivo PhoneNumberType: title: PhoneNumberType type: string enum: - internal - external - virtual CreatePhoneNumberRequest: title: CreatePhoneNumberRequest type: object properties: bundle_id: title: Bundle ID default: null anyOf: - type: string - type: 'null' carrier_type: title: Carrier Type default: null anyOf: - type: string enum: - local - national - mobile - tollfree - type: 'null' country: title: Country description: A two letter ISO country code (e.g. `US` for United States). type: string prefix: title: Prefix description: A string with the phone number prefix or area code, not including the country code. type: string default: '' maxLength: 5 sharing: description: Deprecated. `personal` for a number that belongs to an individual user, or `group` for a group number. The distinction between personal and group numbers is being removed, and this field will be removed in a future update. When omitted, defaults to `personal`. deprecated: true default: personal $ref: '#/components/schemas/PhoneNumberSharing' with_mms: title: With MMS description: By default, MMS-capable numbers are rented if Close supports MMS for the given country. Renting an MMS-capable number can be forced by setting this flag to `true`. If set to `false`, certain prefixes that don't support MMS can be rented in countries where Close supports MMS. In most scenarios, this flag should not be passed. When you request an MMS number, you must set `with_sms` to `true` as well. default: null anyOf: - type: boolean - type: 'null' with_sms: title: With SMS description: By default, SMS-capable numbers are rented if Close supports SMS for the given country. Renting an SMS-capable number can be forced by setting this flag to `true`. If set to `false`, certain prefixes that don't support SMS can be rented in countries where Close supports SMS. In most scenarios, this flag should not be passed unless a `has-voice-only` error status is received. default: null anyOf: - type: boolean - type: 'null' required: - country additionalProperties: false securitySchemes: ApiKeyAuth: description: Use your API key as the username and leave the password empty. scheme: basic type: http OAuth2: flows: authorizationCode: authorizationUrl: https://app.close.com/oauth2/authorize/ scopes: all.full_access: Full access to all resources offline_access: Request a refresh token tokenUrl: https://api.close.com/oauth2/token/ type: oauth2